docs(Python): Initialize itkwasm docs content, update formatting

Add: - Landing index.md - Introduction - API Reference - Links to C++/JavaScript docs Configuration updates: - Furo theme - Myst markdown - sphinx-copybutton - autodoc2 - sphinx opengraph - sphinx-design - Add ReadTheDocs yaml configuration Update main description to include Python.
InsightSoftwareConsortium · Apr 24, 2023 · 990403d · 990403d
1 parent d9a442f
commit 990403d
Show file tree

Hide file tree

Showing 26 changed files with 191 additions and 72 deletions.
diff --git a/.github/workflows/python-wasm.yml b/.github/workflows/python-wasm.yml
@@ -148,6 +148,7 @@ jobs:
           python -m pip install -e "."
           python -m pip install hatch itk pytest
       - name: Build Sphinx documentation
-        working-directory: ./packages/core/python/itkwasm
+        working-directory: ./packages/core/python/itkwasm/docs
         run: |
-          hatch run docs:html
+          python -m pip install -r requirements.txt
+          make html
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,18 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+sphinx:
+  configuration: packages/core/python/itkwasm/docs/conf.py
+
+python:
+   install:
+   - requirements: packages/core/python/itkwasm/docs/requirements.txt
diff --git a/README.md b/README.md
@@ -18,17 +18,17 @@ itk-wasm
 
 *itk-wasm* combines [ITK](https://www.itk.org/) and
 [WebAssembly](https://webassembly.org/) to enable high-performance spatial
-analysis in a web browser, Node.js, and reproducible execution across
+analysis in a web browser, Node.js, Python, and reproducible execution across
 programming languages and hardware architectures.
 
 The project provides tools to a) build C/C++ code to
 [WebAssembly](https://webassembly.org/), b) bridge local filesystems,
-JavaScript/Typescript data structures, and traditional file formats, c)
+JavaScript/TypeScript/Python data structures, and traditional file formats, c)
 transfer data efficiently in and out of the WebAssembly runtime, and d)
 asynchronous, parallel execution of processing pipelines in a worker pool.
 *itk-wasm* can be used to execute [ITK](https://www.itk.org/)
 or arbitrary C++ codes in the browser, on a
-workstation / server with [Node.js](https://nodejs.org/), or standalone
+workstation / server with [Node.js](https://nodejs.org/) or [Python](https://python.org), or standalone
 execution and wrapped in [WASI](https://wasi.dev/) runtimes.
 
 For more information, please see [the project

diff --git a/docs/_coverpage.md b/docs/_coverpage.md
@@ -2,10 +2,8 @@
 
 > Universal spatial analysis and visualization.
 
-*itk-wasm* combines [ITK](https://www.itk.org/) and
-[WebAssembly](https://webassembly.org/) to enable high-performance spatial
-analysis in a web browser, Node.js, and reproducible execution across
-programming languages and hardware architectures.
+*itk-wasm* combines [ITK](https://www.itk.org/) and [WebAssembly](https://webassembly.org/) to enable high-performance spatial analysis in a web browser or system-level environments and reproducible execution across programming languages and hardware architectures.
+
 
 [![Examples](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/examples.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/examples.yml)
 [![Toolchains](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/toolchains.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/toolchains.yml)

diff --git a/docs/docs/README.md b/docs/docs/README.md
@@ -5,22 +5,25 @@
 [![Examples](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/examples.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/examples.yml) [![Toolchains](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/toolchains.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/toolchains.yml) [![JavaScript,TypeScript](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/javascript-typescript.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/javascript-typescript.yml) [![Python WASM](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/python-wasm.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/python-wasm.yml) [![C++,Native Python](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/cxx-python.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/cxx-python.yml) [![WASI](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/wasi.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/wasi.yml)
 
 [![npm version](https://badge.fury.io/js/itk-wasm.svg)](https://www.npmjs.com/package/itk-wasm)
-[![npm version](https://badge.fury.io/py/itkwasm.svg)](https://pypi.org/project/itkwasm/)
-[![npm version](https://badge.fury.io/py/itk-webassemblyinterface.svg)](https://pypi.org/project/itk-webassemblyinterface/)
+[![itkwasm version](https://badge.fury.io/py/itkwasm.svg)](https://pypi.org/project/itkwasm/)
+[![itk-webassemblyinterface version](https://badge.fury.io/py/itk-webassemblyinterface.svg)](https://pypi.org/project/itk-webassemblyinterface/)
 
 [![DOI](https://zenodo.org/badge/45812381.svg)](https://zenodo.org/badge/latestdoi/45812381)
+![License](https://img.shields.io/github/license/InsightSoftwareConsortium/itk-wasm) ![GitHub commit activity](https://img.shields.io/github/commit-activity/y/InsightSoftwareConsortium/itk-wasm)
 </div>
 
-*itk-wasm* combines [ITK](https://www.itk.org/) and [WebAssembly](https://webassembly.org/) to enable high-performance spatial analysis in a web browser, Node.js, and reproducible execution across programming languages and hardware architectures.
+*itk-wasm* combines [ITK](https://www.itk.org/) and [WebAssembly](https://webassembly.org/) to enable high-performance spatial analysis in a web browser or system-level environments and reproducible execution across programming languages and hardware architectures.
 
 The project provides tools to
 
 - build C/C++ code to [WebAssembly](https://webassembly.org/).
-- bridge local filesystems, JavaScript/Typescript data structures, and traditional file formats.
+- bridge local filesystems, JavaScript/TypeScript/Python data structures, and traditional file formats.
 - transfer data efficiently in and out of the WebAssembly runtime.
 - perform asynchronous, parallel execution of processing pipelines in a worker pool.
 
-*itk-wasm* can be used to execute [ITK](https://www.itk.org/) or arbitrary C++ codes in the browser, on a workstation / server with [Node.js](https://nodejs.org/), or standalone execution and wrapped in [WASI](https://wasi.dev/) runtimes.
+*itk-wasm* can be used to execute [ITK](https://www.itk.org/) or arbitrary C++ codes in the browser, on the command line, and in languages like Python via [WASI](https://wasi.dev/) and [Emscripten](https://emscripten.org) runtimes.
+
+This site provides the C++ and JavaScript/TypeScript documentation. There is also [Python documentation](https://itkwasm.readthedocs.io/).
 
 <div align="center">
 <h3><a href="/tutorial/hello_world">Start the tutorial!</a></h3>

diff --git a/docs/release-introduction.md b/docs/release-introduction.md
@@ -1,6 +1,6 @@
 *itk-wasm* combines [ITK](https://www.itk.org/) and [WebAssembly](https://webassembly.org/) to enable high-performance spatial analysis in a web browser, Node.js, and reproducible execution across programming languages and hardware architectures.
 
-The project provides tools to a) build C/C++ code to [WebAssembly](https://webassembly.org/), b) bridge local filesystems, JavaScript/Typescript data structures, and traditional file formats, c) transfer data efficiently in and out of the WebAssembly runtime, and d) asynchronous, parallel execution of processing pipelines in a worker pool.  *itk-wasm* can be used to execute [ITK](https://www.itk.org/) or arbitrary C++ codes in the browser, on a workstation / server with [Node.js](https://nodejs.org/), or standalone execution and wrapped in [WASI](https://wasi.dev/) runtimes.
+The project provides tools to a) build C/C++ code to [WebAssembly](https://webassembly.org/), b) bridge local filesystems, JavaScript/Typescript/Python data structures, and traditional file formats, c) transfer data efficiently in and out of the WebAssembly runtime, and d) asynchronous, parallel execution of processing pipelines in a worker pool.  *itk-wasm* can be used to execute [ITK](https://www.itk.org/) or arbitrary C++ codes in the browser, on a workstation / server with [Node.js](https://nodejs.org/), or standalone execution and wrapped in [WASI](https://wasi.dev/) runtimes.
 
 ## Installation
 

diff --git a/...ss-stringify-emscripten/itkwasm_compress_stringify_emscripten/compress_stringify_async.py b/...ss-stringify-emscripten/itkwasm_compress_stringify_emscripten/compress_stringify_async.py
@@ -50,16 +50,11 @@ async def compress_stringify_async(
 
     output_web_worker = None
     output_list = []
-    print(dir(outputs))
     outputs_object_map = outputs.as_object_map()
     for output_name in outputs.object_keys():
         if output_name == 'webWorker':
             output_web_worker = outputs_object_map[output_name]
         else:
-            print(output_name)
-            print(type(outputs_object_map[output_name]))
-            print(outputs_object_map[output_name].constructor.name)
-            print(outputs_object_map[output_name])
             output_list.append(to_py(outputs_object_map[output_name]))
 
     js_resources.web_worker = output_web_worker

diff --git a/packages/core/python/itkwasm/docs/.gitignore b/packages/core/python/itkwasm/docs/.gitignore
@@ -1 +1,2 @@
 _build/
+apidocs/
diff --git a/packages/core/python/itkwasm/docs/_static/environment-dispatch-mermaid-history.json b/packages/core/python/itkwasm/docs/_static/environment-dispatch-mermaid-history.json
@@ -0,0 +1 @@
+[{"state":{"code":"---\ntitle: itkwasm environment dispatch\n---\nflowchart TD\n    A[fa:fa-box-open itkwasm-package-name] --> B{browser?}\n    A -.-> |pip install| P[accelerator-package]\n    B --> |yes| C[fa:fa-box-open itkwasm-package-name-emscripten]\n    C --> |any OS, architecture| D([Chromium-based browser])\n    C --> |any OS, architecture| E([Firefox])\n    C --> |macOS, x86_64, ARM| F([Safari])\n    B --> |no| wasi[fa:fa-box-open itkwasm-package-name-wasi]\n    wasi --> G{architecture?}\n    G --> H(x86_64)\n    G --> I(ARM)\n    H --> J(Linux)\n    H --> K(macOS)\n    H --> L(Windows)\n    I --> M(Linux)\n    I --> N(macOS)\n    P --> Q(CUDA)\n    P --> R(OpenCL)\n    P --> S(WebGPU)\n    S --> T{browser?}\n    T --> |yes| U[fa:fa-box-open accelerator-package-emscripten]\n    T --> |no| V[fa:fa-box-open accelerator-package-native]\n    \n  ","mermaid":"{\n  \"theme\": \"dark\"\n}","autoSync":true,"updateDiagram":false},"time":1682285480249,"type":"manual","id":"32405602-2e6c-4c68-88e9-4ba6f2e3f6ce","name":"worried-megabyte"}]
diff --git a/packages/core/python/itkwasm/docs/_static/environment-dispatch-mermaid.png b/packages/core/python/itkwasm/docs/_static/environment-dispatch-mermaid.png
diff --git a/packages/core/python/itkwasm/docs/_static/environment-dispatch-mermaid.svg b/packages/core/python/itkwasm/docs/_static/environment-dispatch-mermaid.svg
diff --git a/packages/core/python/itkwasm/docs/_static/icon/favicon-160x160.png b/packages/core/python/itkwasm/docs/_static/icon/favicon-160x160.png
diff --git a/packages/core/python/itkwasm/docs/_static/icon/favicon-16x16.png b/packages/core/python/itkwasm/docs/_static/icon/favicon-16x16.png
diff --git a/packages/core/python/itkwasm/docs/_static/icon/favicon-196x196.png b/packages/core/python/itkwasm/docs/_static/icon/favicon-196x196.png
diff --git a/packages/core/python/itkwasm/docs/_static/icon/favicon-32x32.png b/packages/core/python/itkwasm/docs/_static/icon/favicon-32x32.png
diff --git a/packages/core/python/itkwasm/docs/_static/icon/favicon-96x96.png b/packages/core/python/itkwasm/docs/_static/icon/favicon-96x96.png
diff --git a/packages/core/python/itkwasm/docs/_static/icon/favicon.png b/packages/core/python/itkwasm/docs/_static/icon/favicon.png
diff --git a/packages/core/python/itkwasm/docs/_static/itk-webassembly.png b/packages/core/python/itkwasm/docs/_static/itk-webassembly.png
diff --git a/packages/core/python/itkwasm/docs/_static/logo-white.svg b/packages/core/python/itkwasm/docs/_static/logo-white.svg
diff --git a/packages/core/python/itkwasm/docs/conf.py b/packages/core/python/itkwasm/docs/conf.py
@@ -6,34 +6,49 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+from datetime import date
+
 project = 'itkwasm'
-copyright = '2023, NumFOCUS'
+copyright = f'{date.today().year}, NumFOCUS'
 author = 'Matt McCormick'
 
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+extensions = [
+    'sphinx.ext.napoleon',
+    'autodoc2',
+    'myst_parser',
+    'sphinx.ext.intersphinx',
+    'sphinx_copybutton',
+    'sphinxext.opengraph',
+    'sphinx_design',
+]
 
-extensions = ['sphinx.ext.napoleon', 'sphinx.ext.autodoc']
+myst_enable_extensions = ["colon_fence"]
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+autodoc2_packages = [
+    {
+        "path": "../itkwasm",
+        "exclude_files": ["_to_numpy_array.py",],
+    },
+]
+autodoc2_render_plugin = "myst"
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+}
 
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
-html_theme = 'pydata_sphinx_theme'
+html_theme = 'furo'
 html_static_path = ['_static']
+html_logo = "_static/logo-white.svg"
+html_favicon = "_static/icon/favicon.png"
+html_title = f"{project} python documentation"
 
+# Furo options
 html_theme_options = {
-    "use_edit_page_button": True,
-    "github_url": "https://github.com/InsightSoftwareConsortium/itk-wasm",
-}
-
-html_context = {
-    "github_user": "InsightSoftwareConsortium",
-    "github_repo": "itk-wasm",
-    "github_version": "main",
-    "doc_path": "packages/core/python/itkwasm/docs",
+    "top_of_page_button": "edit",
+    "source_repository": "https://github.com/InsightSoftwareConsortium/itk-wasm/",
+    "source_branch": "main",
+    "source_directory": "packages/core/python/itkwasm/docs",
 }
diff --git a/packages/core/python/itkwasm/docs/index.md b/packages/core/python/itkwasm/docs/index.md
@@ -0,0 +1,44 @@
+itkwasm
+=======
+
+> Universal spatial analysis and visualization.
+
+<div align="center">
+
+![itk-wasm](_static/itk-webassembly.png)
+
+[![Examples](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/examples.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/examples.yml) [![Toolchains](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/toolchains.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/toolchains.yml) [![JavaScript,TypeScript](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/javascript-typescript.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/javascript-typescript.yml) [![Python WASM](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/python-wasm.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/python-wasm.yml) [![C++,Native Python](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/cxx-python.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/cxx-python.yml) [![WASI](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/wasi.yml/badge.svg)](https://github.com/InsightSoftwareConsortium/itk-wasm/actions/workflows/wasi.yml)
+
+[![itkwasm version](https://badge.fury.io/py/itkwasm.svg)](https://pypi.org/project/itkwasm/)
+
+[![DOI](https://zenodo.org/badge/45812381.svg)](https://zenodo.org/badge/latestdoi/45812381)
+
+![License](https://img.shields.io/github/license/InsightSoftwareConsortium/itk-wasm) ![GitHub commit activity](https://img.shields.io/github/commit-activity/y/InsightSoftwareConsortium/itk-wasm)
+</div>
+
+*itk-wasm* combines [ITK](https://www.itk.org/) and [WebAssembly](https://webassembly.org/) to enable high-performance spatial analysis in a web browser or system-level environments and reproducible execution across programming languages and hardware architectures.
+
+The project provides tools to
+
+- build C/C++ code to [WebAssembly](https://webassembly.org/).
+- bridge local filesystems, JavaScript/TypeScript/Python data structures, and traditional file formats.
+- transfer data efficiently in and out of the WebAssembly runtime.
+- perform asynchronous, parallel execution of processing pipelines in a worker pool.
+
+*itk-wasm* can be used to execute [ITK](https://www.itk.org/) or arbitrary C++ codes in the browser, on the command line, and in languages like Python via [WASI](https://wasi.dev/) and [Emscripten](https://emscripten.org) runtimes.
+
+This site provides the Python documentation. There is also [C++ and JavaScript/TypeScript documentation](https://wasm.itk.org/).
+
+```{toctree}
+:hidden:
+introduction.md
+```
+
+```{toctree}
+:hidden:
+:maxdepth: 3
+:caption: 📖 Reference
+
+apidocs/index.rst
+C++/JavaScript Docs <https://wasm.itk.org/>
+```
diff --git a/packages/core/python/itkwasm/docs/index.rst b/packages/core/python/itkwasm/docs/index.rst
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		[{"state":{"code":"---\ntitle: itkwasm environment dispatch\n---\nflowchart TD\n A[fa:fa-box-open itkwasm-package-name] --> B{browser?}\n A -.-> \|pip install\| P[accelerator-package]\n B --> \|yes\| C[fa:fa-box-open itkwasm-package-name-emscripten]\n C --> \|any OS, architecture\| D([Chromium-based browser])\n C --> \|any OS, architecture\| E([Firefox])\n C --> \|macOS, x86_64, ARM\| F([Safari])\n B --> \|no\| wasi[fa:fa-box-open itkwasm-package-name-wasi]\n wasi --> G{architecture?}\n G --> H(x86_64)\n G --> I(ARM)\n H --> J(Linux)\n H --> K(macOS)\n H --> L(Windows)\n I --> M(Linux)\n I --> N(macOS)\n P --> Q(CUDA)\n P --> R(OpenCL)\n P --> S(WebGPU)\n S --> T{browser?}\n T --> \|yes\| U[fa:fa-box-open accelerator-package-emscripten]\n T --> \|no\| V[fa:fa-box-open accelerator-package-native]\n \n ","mermaid":"{\n \"theme\": \"dark\"\n}","autoSync":true,"updateDiagram":false},"time":1682285480249,"type":"manual","id":"32405602-2e6c-4c68-88e9-4ba6f2e3f6ce","name":"worried-megabyte"}]