feat: improve docs

.github/workflows/ci.yaml

@@ -51,6 +51,12 @@ jobs:
       - name: Config Bundle Codegen
         run: yarn codegen
         if: contains(matrix.package, 'config-bundles')
+      - name: Client Codegen
+        run: yarn codegen
+        if: endsWith(matrix.package, 'polywrap-client')
+      - name: Client Config Builder Codegen
+        run: yarn codegen
+        if: endsWith(matrix.package, 'polywrap-client-config-builder')
       - name: Typecheck
         run: poetry run tox -e typecheck
       - name: Lint

docs/docgen.sh

@@ -1,8 +1,16 @@
-sphinx-apidoc ../packages/polywrap-msgpack/polywrap_msgpack -o ./source/polywrap-msgpack -e
-sphinx-apidoc ../packages/polywrap-manifest/polywrap_manifest -o ./source/polywrap-manifest -e
-sphinx-apidoc ../packages/polywrap-core/polywrap_core -o ./source/polywrap-core -e
-sphinx-apidoc ../packages/polywrap-wasm/polywrap_wasm -o ./source/polywrap-wasm -e
-sphinx-apidoc ../packages/polywrap-plugin/polywrap_plugin -o ./source/polywrap-plugin -e
-sphinx-apidoc ../packages/polywrap-uri-resolvers/polywrap_uri_resolvers -o ./source/polywrap-uri-resolvers -e
-sphinx-apidoc ../packages/polywrap-client/polywrap_client -o ./source/polywrap-client -e
-sphinx-apidoc ../packages/polywrap-client-config-builder/polywrap_client_config_builder -o ./source/polywrap-client-config-builder -e
+sphinx-apidoc ../packages/polywrap-msgpack/polywrap_msgpack -o ./source/polywrap-msgpack -e  -M -t ./source/_templates -d 2
+sphinx-apidoc ../packages/polywrap-manifest/polywrap_manifest -o ./source/polywrap-manifest -e  -M -t ./source/_templates -d 2
+sphinx-apidoc ../packages/polywrap-core/polywrap_core -o ./source/polywrap-core -e  -M -t ./source/_templates -d 2
+sphinx-apidoc ../packages/polywrap-wasm/polywrap_wasm -o ./source/polywrap-wasm -e  -M -t ./source/_templates -d 2
+sphinx-apidoc ../packages/polywrap-plugin/polywrap_plugin -o ./source/polywrap-plugin -e  -M -t ./source/_templates -d 2
+sphinx-apidoc ../packages/polywrap-uri-resolvers/polywrap_uri_resolvers -o ./source/polywrap-uri-resolvers -e  -M -t ./source/_templates -d 2
+sphinx-apidoc ../packages/polywrap-client/polywrap_client -o ./source/polywrap-client -e  -M -t ./source/_templates -d 2
+sphinx-apidoc ../packages/polywrap-client-config-builder/polywrap_client_config_builder -o ./source/polywrap-client-config-builder -e  -M -t ./source/_templates -d 2
+sphinx-apidoc ../packages/plugins/polywrap-fs-plugin/polywrap_fs_plugin -o ./source/polywrap-fs-plugin -e  -M -t ./source/_templates -d 2
+sphinx-apidoc ../packages/plugins/polywrap-http-plugin/polywrap_http_plugin -o ./source/polywrap-http-plugin -e  -M -t ./source/_templates -d 2
+sphinx-apidoc ../packages/plugins/polywrap-ethereum-provider/polywrap_ethereum_provider -o ./source/polywrap-ethereum-provider -e  -M -t ./source/_templates -d 2
+sphinx-apidoc ../packages/config-bundles/polywrap-sys-config-bundle/polywrap_sys_config_bundle -o ./source/polywrap-sys-config-bundle -e  -M -t ./source/_templates -d 2
+sphinx-apidoc ../packages/config-bundles/polywrap-web3-config-bundle/polywrap_web3_config_bundle -o ./source/polywrap-web3-config-bundle -e  -M -t ./source/_templates -d 2
+
+cd ../packages/polywrap-client && python scripts/extract_readme.py && cd ../../docs
+cp ../packages/polywrap-client/README.rst ./source/Quickstart.rst

docs/pyproject.toml

@@ -18,7 +18,14 @@ polywrap-plugin = { path = "../packages/polywrap-plugin", develop = true }
 polywrap-uri-resolvers = { path = "../packages/polywrap-uri-resolvers", develop = true }
 polywrap-client = { path = "../packages/polywrap-client", develop = true }
 polywrap-client-config-builder = { path = "../packages/polywrap-client-config-builder", develop = true }
+polywrap-fs-plugin = { path = "../packages/plugins/polywrap-fs-plugin", develop = true }
+polywrap-http-plugin = { path = "../packages/plugins/polywrap-http-plugin", develop = true }
+polywrap-ethereum-provider = { path = "../packages/plugins/polywrap-ethereum-provider", develop = true }
+polywrap-sys-config-bundle = { path = "../packages/config-bundles/polywrap-sys-config-bundle", develop = true }
+polywrap-web3-config-bundle = { path = "../packages/config-bundles/polywrap-web3-config-bundle", develop = true }
 
 [tool.poetry.group.dev.dependencies]
 sphinx = "^6.1.3"
-sphinx-rtd-theme = "^1.2.0"
+sphinx-rtd-theme = "^1.2.0"
+myst-parser = "^2.0.0"
+sphinx-mdinclude = "^0.5.3"

docs/source/Quickstart.rst

@@ -0,0 +1,41 @@
+Polywrap Client
+===============
+This package contains the implementation of polywrap python client.
+
+Quickstart
+==========
+
+Imports
+-------
+
+>>> from polywrap_core import Uri, ClientConfig
+>>> from polywrap_client import PolywrapClient
+>>> from polywrap_client_config_builder import PolywrapClientConfigBuilder
+>>> from polywrap_sys_config_bundle import sys_bundle
+>>> from polywrap_web3_config_bundle import web3_bundle
+
+Configure and Instantiate
+-------------------------
+
+>>> builder = (
+...     PolywrapClientConfigBuilder()
+...     .add_bundle(sys_bundle)
+...     .add_bundle(web3_bundle)
+... )
+>>> config = builder.build()
+>>> client = PolywrapClient(config)
+
+Invocation
+----------
+
+Invoke a wrapper.
+
+>>> uri = Uri.from_str(
+...     'wrapscan.io/polywrap/ipfs-http-client'
+... )
+>>> args = {
+...     "cid": "QmZ4d7KWCtH3xfWFwcdRXEkjZJdYNwonrCwUckGF1gRAH9",
+...     "ipfsProvider": "https://ipfs.io",
+... }
+>>> result = client.invoke(uri=uri, method="cat", args=args, encode_result=False)
+>>> assert result.startswith(b"<svg")

docs/source/_templates/module.rst_t

@@ -0,0 +1,8 @@
+{%- if show_headings %}
+{{- [basename, "module"] | join(' ') | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}

docs/source/_templates/package.rst_t

@@ -0,0 +1,42 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{%- if is_namespace %}
+{{- [pkgname, "namespace"] | join(" ") | e | heading }}
+{% else %}
+{{- [pkgname, "package"] | join(" ") | e | heading }}
+{% endif %}
+
+{%- if subpackages %}
+Subpackages
+-----------
+
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+Submodules
+----------
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule, "module"] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{%- endif %}

docs/source/_templates/toc.rst_t

@@ -0,0 +1,15 @@
+{{ header | heading }}
+
+.. automodule:: {% for docname in docnames %}{{ docname }}{%- endfor %}
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+API References
+--------------
+
+.. toctree::
+   :maxdepth: 4
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}

docs/source/index.rst

@@ -6,19 +6,26 @@
 Welcome to polywrap-client's documentation!
 ===========================================
 
+.. include:: Quickstart.rst
+
+
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
 
+   polywrap-client/modules.rst
+   polywrap-client-config-builder/modules.rst
+   polywrap-fs-plugin/modules.rst
+   polywrap-http-plugin/modules.rst
+   polywrap-ethereum-provider/modules.rst
+   polywrap-sys-config-bundle/modules.rst
+   polywrap-web3-config-bundle/modules.rst
    polywrap-msgpack/modules.rst
    polywrap-manifest/modules.rst
    polywrap-core/modules.rst
    polywrap-wasm/modules.rst
    polywrap-plugin/modules.rst
    polywrap-uri-resolvers/modules.rst
-   polywrap-client/modules.rst
-   polywrap-client-config-builder/modules.rst
-
 
 Indices and tables
 ==================

docs/source/polywrap-client-config-builder/modules.rst

@@ -1,7 +1,15 @@
 polywrap_client_config_builder
 ==============================
 
+.. automodule:: polywrap_client_config_builder
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+API References
+--------------
+
 .. toctree::
    :maxdepth: 4
 
-   polywrap_client_config_builder
+   polywrap_client_config_builder

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.configures.base_configure.rst

@@ -4,4 +4,4 @@ polywrap\_client\_config\_builder.configures.base\_configure module
 .. automodule:: polywrap_client_config_builder.configures.base_configure
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.configures.env_configure.rst

@@ -4,4 +4,4 @@ polywrap\_client\_config\_builder.configures.env\_configure module
 .. automodule:: polywrap_client_config_builder.configures.env_configure
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.configures.interface_configure.rst

@@ -4,4 +4,4 @@ polywrap\_client\_config\_builder.configures.interface\_configure module
 .. automodule:: polywrap_client_config_builder.configures.interface_configure
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.configures.package_configure.rst

@@ -4,4 +4,4 @@ polywrap\_client\_config\_builder.configures.package\_configure module
 .. automodule:: polywrap_client_config_builder.configures.package_configure
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.configures.redirect_configure.rst

@@ -4,4 +4,4 @@ polywrap\_client\_config\_builder.configures.redirect\_configure module
 .. automodule:: polywrap_client_config_builder.configures.redirect_configure
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.configures.resolver_configure.rst

@@ -4,4 +4,4 @@ polywrap\_client\_config\_builder.configures.resolver\_configure module
 .. automodule:: polywrap_client_config_builder.configures.resolver_configure
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.configures.rst

@@ -5,7 +5,7 @@ Submodules
 ----------
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 2
 
    polywrap_client_config_builder.configures.base_configure
    polywrap_client_config_builder.configures.env_configure
@@ -14,11 +14,3 @@ Submodules
    polywrap_client_config_builder.configures.redirect_configure
    polywrap_client_config_builder.configures.resolver_configure
    polywrap_client_config_builder.configures.wrapper_configure
-
-Module contents
----------------
-
-.. automodule:: polywrap_client_config_builder.configures
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.configures.wrapper_configure.rst

@@ -4,4 +4,4 @@ polywrap\_client\_config\_builder.configures.wrapper\_configure module
 .. automodule:: polywrap_client_config_builder.configures.wrapper_configure
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.polywrap_client_config_builder.rst

@@ -4,4 +4,4 @@ polywrap\_client\_config\_builder.polywrap\_client\_config\_builder module
 .. automodule:: polywrap_client_config_builder.polywrap_client_config_builder
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.rst

@@ -5,7 +5,7 @@ Subpackages
 -----------
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 2
 
    polywrap_client_config_builder.configures
    polywrap_client_config_builder.types
@@ -14,14 +14,6 @@ Submodules
 ----------
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 2
 
    polywrap_client_config_builder.polywrap_client_config_builder
-
-Module contents
----------------
-
-.. automodule:: polywrap_client_config_builder
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.types.build_options.rst

@@ -4,4 +4,4 @@ polywrap\_client\_config\_builder.types.build\_options module
 .. automodule:: polywrap_client_config_builder.types.build_options
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.types.builder_config.rst

@@ -4,4 +4,4 @@ polywrap\_client\_config\_builder.types.builder\_config module
 .. automodule:: polywrap_client_config_builder.types.builder_config
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.types.bundle_package.rst

@@ -0,0 +1,7 @@
+polywrap\_client\_config\_builder.types.bundle\_package module
+==============================================================
+
+.. automodule:: polywrap_client_config_builder.types.bundle_package
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.types.client_config_builder.rst

@@ -4,4 +4,4 @@ polywrap\_client\_config\_builder.types.client\_config\_builder module
 .. automodule:: polywrap_client_config_builder.types.client_config_builder
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/source/polywrap-client-config-builder/polywrap_client_config_builder.types.rst

@@ -5,16 +5,9 @@ Submodules
 ----------
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 2
 
    polywrap_client_config_builder.types.build_options
    polywrap_client_config_builder.types.builder_config
+   polywrap_client_config_builder.types.bundle_package
    polywrap_client_config_builder.types.client_config_builder
-
-Module contents
----------------
-
-.. automodule:: polywrap_client_config_builder.types
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/source/polywrap-client/modules.rst

@@ -1,7 +1,15 @@
 polywrap_client
 ===============
 
+.. automodule:: polywrap_client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+API References
+--------------
+
 .. toctree::
    :maxdepth: 4
 
-   polywrap_client
+   polywrap_client

docs/source/polywrap-client/polywrap_client.client.rst

@@ -4,4 +4,4 @@ polywrap\_client.client module
 .. automodule:: polywrap_client.client
    :members:
    :undoc-members:
-   :show-inheritance:
+   :show-inheritance:

docs/source/polywrap-client/polywrap_client.errors.rst

@@ -0,0 +1,7 @@
+polywrap\_client.errors module
+==============================
+
+.. automodule:: polywrap_client.errors
+   :members:
+   :undoc-members:
+   :show-inheritance: