add sphinx ext to auto gen api docs

Author: rmorshea

docs/source/_exts/autogen_api_docs.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+
+from sphinx.application import Sphinx
+
+
+HERE = Path(__file__).parent
+PACKAGE_SRC = HERE.parent.parent.parent / "src"
+PUBLIC_API_REFERENCE_FILE = HERE.parent / "api-reference.rst"
+PRIVATE_API_REFERENCE_FILE = HERE.parent / "developer-apis.rst"
+
+
+PUBLIC_TITLE = """API Reference
+=============
+"""
+
+PRIVATE_TITLE = """Developer APIs
+==============
+"""
+
+AUTODOC_TEMPLATE = """
+.. automodule:: {module}
+    :members:
+"""
+
+
+def make_autodoc_section(module_name: str) -> str:
+    return AUTODOC_TEMPLATE.format(module=module_name, underline="-" * len(module_name))
+
+
+def generate_api_docs():
+    public_docs = [PUBLIC_TITLE]
+    private_docs = [PRIVATE_TITLE]
+
+    for file in sorted(PACKAGE_SRC.glob("**/*.py")):
+        if file.stem.startswith("__"):
+            # skip __init__ and __main__
+            continue
+        rel_path = file.relative_to(PACKAGE_SRC)
+        module_name = ".".join(rel_path.with_suffix("").parts)
+        api_docs = make_autodoc_section(module_name)
+        (private_docs if "._" in module_name else public_docs).append(api_docs)
+
+    PUBLIC_API_REFERENCE_FILE.write_text("\n".join(public_docs))
+    PRIVATE_API_REFERENCE_FILE.write_text("\n".join(private_docs))
+
+
+def setup(app: Sphinx) -> None:
+    generate_api_docs()
+    return None

docs/source/package-api.rst renamed to docs/source/api-reference.rst

@@ -1,106 +1,98 @@
-Package API
-===========
+API Reference
+=============
 
-.. module:: idom
 
+.. automodule:: idom.cli
+    :members:
 
-Component
----------
 
-.. automodule:: idom.core.component
+.. automodule:: idom.client.manage
     :members:
 
 
-Hooks
------
-
-.. automodule:: idom.core.hooks
+.. automodule:: idom.client.module
     :members:
 
 
-Layout
-------
-
-.. automodule:: idom.core.layout
+.. automodule:: idom.config
     :members:
 
 
-Dispatcher
-----------
+.. automodule:: idom.core.component
+    :members:
+
 
 .. automodule:: idom.core.dispatcher
     :members:
 
 
-Server Base
------------
-
-.. automodule:: idom.server.base
+.. automodule:: idom.core.events
     :members:
 
 
-Sanic Servers
--------------
-
-.. automodule:: idom.server.sanic
+.. automodule:: idom.core.hooks
     :members:
 
 
-Flask Servers
--------------
-
-.. automodule:: idom.server.flask
+.. automodule:: idom.core.layout
     :members:
 
 
-FastAPI Servers
----------------
+.. automodule:: idom.core.utils
+    :members:
 
-.. automodule:: idom.server.fastapi
+
+.. automodule:: idom.core.vdom
     :members:
 
 
-Tornado Servers
----------------
+.. automodule:: idom.dialect
+    :members:
+
 
-.. automodule:: idom.server.tornado
+.. automodule:: idom.log
     :members:
 
 
-HTML Widgets
-------------
+.. automodule:: idom.server.base
+    :members:
 
-.. automodule:: idom.widgets.html
+
+.. automodule:: idom.server.fastapi
     :members:
-    :undoc-members:
 
 
-Widget Tools
-------------
+.. automodule:: idom.server.flask
+    :members:
 
-.. automodule:: idom.widgets.utils
+
+.. automodule:: idom.server.prefab
     :members:
 
 
-Dialect
--------
+.. automodule:: idom.server.sanic
+    :members:
+
 
-.. automodule:: idom.dialect
+.. automodule:: idom.server.tornado
     :members:
 
 
-Client
-------
+.. automodule:: idom.server.utils
+    :members:
 
-.. automodule:: idom.client.module
+
+.. automodule:: idom.testing
     :members:
 
-.. automodule:: idom.client.manage
+
+.. automodule:: idom.utils
     :members:
 
 
-Useful Tools
-------------
+.. automodule:: idom.widgets.html
+    :members:
+
 
-.. automodule:: idom.utils
+.. automodule:: idom.widgets.utils
     :members:

docs/source/conf.py

@@ -53,11 +53,14 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.extlinks",
     "sphinx.ext.autosectionlabel",
+    # third party extensions
     "sphinx_autodoc_typehints",
     "sphinx_panels",
     "sphinx_copybutton",
+    "sphinx_reredirects",
     # custom extensions
     "async_doctest",
+    "autogen_api_docs",
     "copy_vdom_json_schema",
     "interactive_widget",
     "patched_html_translator",
@@ -113,6 +116,13 @@
 # order autodoc members by their order in the source
 autodoc_member_order = "bysource"
 
+# -- sphinx_reredirects --
+
+redirects = {
+    "package-api": "api-reference.html",
+    "configuration-options": "api-reference.html#configuration-options",
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/source/configuration-options.rst

@@ -0,0 +1,10 @@
+Developer APIs
+==============
+
+
+.. automodule:: idom._option
+    :members:
+
+
+.. automodule:: idom.client._private
+    :members:

docs/source/developer-apis.rst

@@ -10,7 +10,7 @@ Libraries for defining and controlling interactive webpages with Python
     installation
     getting-started
     life-cycle-hooks
-    package-api
+    api-reference
     examples
 
 .. toctree::
@@ -20,7 +20,6 @@ Libraries for defining and controlling interactive webpages with Python
     core-concepts
     javascript-components
     command-line
-    configuration-options
     specifications
 
 .. toctree::
@@ -29,6 +28,7 @@ Libraries for defining and controlling interactive webpages with Python
 
     contributing
     developer-guide
+    developer-apis
     changelog
     roadmap
 

docs/source/index.rst

@@ -5,3 +5,4 @@ sphinx-panels ==0.5.0
 setuptools_scm
 sphinx-copybutton ==0.3.0
 sphinx-autobuild ==2020.9.1
+sphinx-reredirects ==0.0.1

requirements/build-docs.txt

@@ -53,7 +53,6 @@
     "Import",
     "hotswap",
     "multiview",
-    "JupyterDisplay",
     "html_to_vdom",
     "VdomDict",
     "widgets",

src/idom/__init__.py

@@ -1,3 +1,8 @@
+"""
+Client Manager
+==============
+"""
+
 import shutil
 import subprocess
 from logging import getLogger
@@ -49,6 +54,7 @@ def web_module_exists(package_name: str) -> bool:
 
 
 def web_module_names() -> Set[str]:
+    """Get the names of all installed web modules"""
     names = []
     web_mod_dir = _private.web_modules_dir()
     for pth in web_mod_dir.glob("**/*.js"):
@@ -63,6 +69,7 @@ def web_module_names() -> Set[str]:
 
 
 def add_web_module(package_name: str, source: Union[Path, str]) -> str:
+    """Add a web module from source"""
     source = Path(source)
     if not source.exists():
         raise FileNotFoundError(f"Package source file does not exist: {str(source)!r}")
@@ -81,6 +88,7 @@ def build(
     clean_build: bool = True,
     skip_if_already_installed: bool = True,
 ) -> None:
+    """Build the client"""
     package_specifiers_to_install = list(packages)
     del packages  # delete since we just renamed it
 

src/idom/client/manage.py

@@ -1,3 +1,8 @@
+"""
+Client Modules
+==============
+"""
+
 from __future__ import annotations
 
 from pathlib import Path

src/idom/client/module.py

@@ -1,3 +1,11 @@
+"""
+Configuration Options
+=====================
+
+IDOM provides a series of configuration options that can be set using environment
+variables or, for those which allow it, a programatic interface.
+"""
+
 from pathlib import Path
 from typing import cast
 

src/idom/config.py

@@ -1,3 +1,8 @@
+"""
+Component
+=========
+"""
+
 from __future__ import annotations
 
 import abc
@@ -17,8 +22,7 @@ def component(function: ComponentRenderFunction) -> Callable[..., "Component"]:
     """A decorator for defining an :class:`Component`.
 
     Parameters:
-        function:
-            The function that will render a :ref:`VDOM <VDOM Mimetype>` model.
+        function: The function that will render a :class:`VdomDict`.
     """
 
     @wraps(function)
@@ -38,7 +42,7 @@ class AbstractComponent(abc.ABC):
 
     @abc.abstractmethod
     def render(self) -> VdomDict:
-        """Render the component's :ref:`VDOM <VDOM Mimetype>` model."""
+        """Render the component's :class:`VdomDict`."""
 
 
 class Component(AbstractComponent):

src/idom/core/component.py

@@ -1,3 +1,8 @@
+"""
+Dispatchers
+===========
+"""
+
 from __future__ import annotations
 
 import sys

src/idom/core/dispatcher.py

@@ -1,3 +1,7 @@
+"""
+Events
+"""
+
 import asyncio
 from typing import (
     Any,

src/idom/core/events.py

@@ -1,3 +1,8 @@
+"""
+Hooks
+=====
+"""
+
 from __future__ import annotations
 
 import asyncio