jbms · jbms · Jul 5, 2022 · May 5, 2022 · May 5, 2022 · May 5, 2022
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -37,9 +37,9 @@ jobs:
     - run: npm run check
     - name: Install Python packaging & linting tools
       run: python -m pip install -r dev-requirements.txt -r requirements.txt
-    - run: mypy sphinx_immaterial/*.py
-    - run: pylint sphinx_immaterial/*.py
-    - run: black --diff --color sphinx_immaterial/*.py
+    - run: mypy sphinx_immaterial/**/*.py
+    - run: pylint sphinx_immaterial/**/*.py
+    - run: black --diff --color sphinx_immaterial/**/*.py
     - name: Check for dirty working directory
       run: git diff --exit-code
     - name: Show package version
@@ -55,12 +55,14 @@ jobs:
           dist/*.tar.*
     - name: Install wheel and docs' dependencies
       run: pip install dist/*.whl -r docs/requirements.txt
+    - run: pytest -vv -s tests/
+      name: Run Python tests
     - name: Build html docs
       working-directory: docs
-      run: sphinx-build . _build/html
+      run: sphinx-build . _build/html -W --keep-going -T
     - name: Build latex docs
       working-directory: docs
-      run: sphinx-build -b latex . _build/latex
+      run: sphinx-build -b latex . _build/latex -W --keep-going -T
     - name: Upload doc builds as artifacts
       if: ${{ matrix.python-version == '3.10' }}
       uses: actions/upload-artifact@v2

diff --git a/.gitignore b/.gitignore
@@ -14,7 +14,7 @@ __pycache__/
 
 # Sphinx documentation
 docs/_build/
-docs/generated/
+docs/python_apigen_generated/
 
 # mypy
 .mypy_cache/

diff --git a/.pylintrc b/.pylintrc
@@ -111,7 +111,9 @@ disable=raw-checker-failed,
         too-many-instance-attributes,
         bad-option-value,
         too-many-return-statements,
-        line-too-long
+        line-too-long,
+        fixme,
+        cyclic-import
 
 # Enable the message, report, category or checker with the given id(s). You can
 # either give multiple identifier separated by comma (,) or put this option

diff --git a/README.rst b/README.rst
@@ -20,14 +20,11 @@ of a Sphinx theme based on an earlier version of the `mkdocs-material
 significantly diverged from the upstream `mkdocs-material
 <https://squidfunk.github.io/mkdocs-material/>`__ repository.
 
-See the `TensorStore documentation <https://google.github.io/tensorstore/>`__
-for a demonstration of this theme.
-
-WARNING: This theme is currently still a work in progress.  The documentation is
-largely copied from `sphinx-material
-<https://github.com/bashtage/sphinx-material>`__ and is inaccurate for this
-version.  It does not yet integrate well with numpydoc or the built-in
-autosummary.
+See `this theme's own documentation
+<https://jbms.github.io/sphinx-immaterial/>`__ for a demonstration.
+
+WARNING: This theme is still in beta.  While it is already very usable, breaking
+changes will still be made prior to the 1.0 release.
 
 Installation
 ------------

diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -5,3 +5,4 @@ mypy
 types-PyYAML
 docutils-stubs
 types-jsonschema
+pytest
diff --git a/docs/additional_samples.rst b/docs/additional_samples.rst
@@ -35,8 +35,8 @@ Here's an included example with line numbers.
 
 .. rst-example::
 
-   .. literalinclude:: ../sphinx_immaterial/autodoc_property_type.py
-      :caption: source from this theme in *sphinx_immaterial/autodoc_property_type.py*
+   .. literalinclude:: ../sphinx_immaterial/apidoc/python/autodoc_property_type.py
+      :caption: source from this theme in *sphinx_immaterial/apidoc/python/autodoc_property_type.py*
       :linenos:
 
 It also works with existing Sphinx highlighting:
@@ -189,7 +189,7 @@ Alignment
    .. list-table:: Center Aligned
       :header-rows: 1
       :align: center
-   
+
       * - Column 1
         - Column 2
       * - Item 1
@@ -202,7 +202,7 @@ Alignment
       :widths: 15 10 30
       :header-rows: 1
       :align: right
-   
+
       * - Treat
         - Quantity
         - Description
@@ -216,30 +216,6 @@ Alignment
         - 1.99
         - On a stick!
 
-Code Documentation
-==================
-
-
-.. rst-example:: An example Python function.
-
-   .. py:function:: format_exception(etype, value, tb[, limit=None])
-
-      Format the exception with a traceback.
-
-      :param etype: exception type
-      :param value: exception value
-      :param tb: traceback object
-      :param limit: maximum number of stack frames to show
-      :type limit: integer or None
-      :rtype: list of strings
-
-.. rst-example:: An example JavaScript function.
-
-   .. js:class:: MyAnimal(name[, age])
-
-      :param string name: The name of the animal
-      :param number age: an optional age for the animal
-
 Glossaries
 ==========
 
@@ -269,33 +245,37 @@ Math
 .. rst-example::
 
    .. math::
-   
+
       (a + b)^2  &=  (a + b)(a + b) \\
                  &=  a^2 + 2ab + b^2
 
 .. rst-example::
 
    .. math::
       :nowrap:
-   
+
       \begin{eqnarray}
          y    & = & ax^2 + bx + c \\
          f(x) & = & x^2 + 2xy + y^2
       \end{eqnarray}
 
-Production Lists
-================
 
-.. rst-example::
+..
+   FIXME: Production lists currently do not work.
+
+   Production Lists
+   ================
+
+   .. rst-example::
 
-   .. productionlist::
-      try_stmt: try1_stmt | try2_stmt
-      try1_stmt: "try" ":" `suite`
-               : ("except" [`expression` ["," `target`]] ":" `suite`)+
-               : ["else" ":" `suite`]
-               : ["finally" ":" `suite`]
-      try2_stmt: "try" ":" `suite`
-               : "finally" ":" `suite`
+      .. productionlist::
+         try_stmt: try1_stmt | try2_stmt
+         try1_stmt: "try" ":" `suite`
+                  : ("except" [`expression` ["," `target`]] ":" `suite`)+
+                  : ["else" ":" `suite`]
+                  : ["finally" ":" `suite`]
+         try2_stmt: "try" ":" `suite`
+                  : "finally" ":" `suite`
 
 Sub-pages
 =========

diff --git a/docs/cppreference.rst → docs/apidoc/cpp/cppreference.rst b/docs/cppreference.rst → docs/apidoc/cpp/cppreference.rst
@@ -1,17 +1,18 @@
 Automatic cross-linking to cppreference.com
 ===========================================
 
-This theme provides an optional :python:`sphinx_immaterial.cppreference`
-extension that provides automatic linking to C/C++ standard symbols documented
-at https://cppreference.com.
+This theme provides an optional
+:python:`sphinx_immaterial.apidoc.cpp.cppreference` extension that provides
+automatic linking to C/C++ standard symbols documented at
+https://cppreference.com.
 
 To use this extension, simply add it to the list of extensions in :file:`conf.py`:
 
 .. code-block:: python
 
     extensions = [
         # other extensions...
-        "sphinx_immaterial.cppreference",
+        "sphinx_immaterial.apidoc.cpp.cppreference",
     ]
 
 .. rst-example::

diff --git a/docs/external_cpp_references.rst → docs/apidoc/cpp/external_cpp_references.rst b/docs/external_cpp_references.rst → docs/apidoc/cpp/external_cpp_references.rst
@@ -2,10 +2,10 @@ External C++ symbol links
 =========================
 
 This theme includes an optional
-:python:`sphinx_immaterial.external_cpp_references` extension that allows normal
-C++ symbol references, e.g. through the :rst:role:`cpp:expr` role or in C++
-function signatures, to resolve to externally-defined C++ symbols that are
-manually specified in :file:`conf.py`.  Unlike the `sphinx.ext.intersphinx`
+:python:`sphinx_immaterial.apidoc.cpp.external_cpp_references` extension that
+allows normal C++ symbol references, e.g. through the :rst:role:`cpp:expr` role
+or in C++ function signatures, to resolve to externally-defined C++ symbols that
+are manually specified in :file:`conf.py`.  Unlike the `sphinx.ext.intersphinx`
 extension, template arguments are stripped when resolving references, which
 allows template entities to be resolved based on their base name.
 
@@ -16,13 +16,13 @@ define the :confval:`external_cpp_references` configuration option:
 
     extensions = [
         # other extensions...
-        "sphinx_immaterial.external_cpp_references",
+        "sphinx_immaterial.apidoc.cpp.external_cpp_references",
     ]
 
-.. literalinclude:: conf.py
+.. literalinclude:: /conf.py
    :language: python
-   :start-after: # BEGIN: sphinx_immaterial.external_cpp_references extension options
-   :end-before: # END: sphinx_immaterial.external_cpp_references extension options
+   :start-after: # BEGIN: sphinx_immaterial.apidoc.cpp.external_cpp_references extension options
+   :end-before: # END: sphinx_immaterial.apidoc.cpp.external_cpp_references extension options
 
 .. rst-example::
 

diff --git a/docs/cpp.rst → docs/apidoc/cpp/index.rst b/docs/cpp.rst → docs/apidoc/cpp/index.rst
@@ -9,7 +9,7 @@ C++ domain customization
 
    For example, with the following in :file:`conf.py`:
 
-   .. literalinclude:: conf.py
+   .. literalinclude:: /conf.py
       :language: python
       :start-after: # BEGIN: cpp_strip_namespaces_from_signatures option
       :end-before: # END: cpp_strip_namespaces_from_signatures option

diff --git a/docs/format_signatures.rst → docs/apidoc/format_signatures.rst b/docs/format_signatures.rst → docs/apidoc/format_signatures.rst
@@ -48,7 +48,7 @@ following to :file:`conf.py`:
                       other_param: list[str], \
                       yet_another: bool = False, \
                       finally_another: str = "some long string goes here"\
-                    ) -> Tuple[A, Very, Long, Return, Type]
+                    ) -> Tuple[str, bool, float, bytes, int]
 
 clang-format-based function parameter wrapping
 -----------------------------------------------
@@ -66,7 +66,7 @@ which the extension should be used.
 
     extensions = [
         # other extensions...
-        "sphinx_immaterial.format_signatures",
+        "sphinx_immaterial.apidoc.format_signatures",
     ]
 
     object_description_options = [

diff --git a/docs/api.rst → docs/apidoc/index.rst b/docs/api.rst → docs/apidoc/index.rst
@@ -141,6 +141,8 @@ Other options described elsewhere include:
 - :objconf:`wrap_signatures_column_limit`
 - :objconf:`clang_format_style`
 
+.. _object-toc-icons:
+
 Table of contents icons
 ^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/json.rst → docs/apidoc/json/domain.rst b/docs/json.rst → docs/apidoc/json/domain.rst
@@ -19,16 +19,16 @@ feature of this package as a dependency:
 Configuration
 -------------
 
-To use this domain, add :python:`sphinx_immaterial.json_domain` to the list of
-:python:`extensions` in :file:`conf.py` and set the :confval:`json_schemas`
-configuration option to a list of glob patterns specifying the JSON schema
-definition files.
+To use this domain, add :python:`sphinx_immaterial.apidoc.json.domain` to the
+list of :python:`extensions` in :file:`conf.py` and set the
+:confval:`json_schemas` configuration option to a list of glob patterns
+specifying the JSON schema definition files.
 
 .. code-block:: python
 
     extensions = [
         # other extensions...
-        "sphinx_immaterial.json_domain",
+        "sphinx_immaterial.apidoc.json.domain",
     ]
 
     json_schemas = [
@@ -84,7 +84,7 @@ Usage
       Flag option to exclude the schema from search results and the table of
       contents.  Also disables cross linking.
 
-      This option implies :rst:dir:`exclude_from_toc`.
+      This option implies :rst:dir:`json:schema:exclude_from_toc`.
 
    .. rst:directive:option:: title
 
@@ -93,7 +93,7 @@ Usage
    .. rst:directive:option:: toc_title
 
       Specifies the title to use in the table of contents instead of the
-      :rst:dir:`title` or ``$id``.
+      :rst:dir:`json:schema:title` or ``$id``.
 
       Only has an effect if :objconf:`include_in_toc` is :python:`True`.
 

diff --git a/docs/index_transform_schema.yml → docs/apidoc/json/index_transform_schema.yml b/docs/index_transform_schema.yml → docs/apidoc/json/index_transform_schema.yml
diff --git a/docs/inheritance_schema.yml → docs/apidoc/json/inheritance_schema.yml b/docs/inheritance_schema.yml → docs/apidoc/json/inheritance_schema.yml