Add aggregate AutoAPI reference built from httk-core/httk-atomistic submodules

Author: rartino

.github/workflows/docs.yml

@@ -28,7 +28,7 @@ jobs:
 
       - name: Install project + docs deps
         run: |
-          pip install -e .[docs]
+          pip install -e .[docs] -e submodules/httk-core -e submodules/httk-atomistic
 
       - name: Build docs
         run: make docs

.gitignore

@@ -1,7 +1,9 @@
 *~
 \#*\#
 .\#*
-docs/reference/autoapi
+# AutoAPI output is generated at build time from the submodule sources; the src/
+# symlinks and the submodules/ checkouts themselves are tracked and must NOT be ignored.
+docs/reference/autoapi/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "submodules/httk-core"]
 	path = submodules/httk-core
 	url = https://github.com/httk/httk-core
+[submodule "submodules/httk-atomistic"]
+	path = submodules/httk-atomistic
+	url = https://github.com/httk/httk-atomistic

Makefile

@@ -1,37 +1,21 @@
 PYTHON ?= python3
 
-.PHONY: docs docs-clean format format-check typecheck_pyright typecheck lint
+# Base URL of the published httk documentation site, used for cross-linking docs
+# between httk repositories (read by docs/conf.py via HTTK_DOCS_BASE_URL).
+DOCS_BASE_URL ?= https://docs.httk.org
 
-docs:
-	$(PYTHON) -m sphinx -b html -W --keep-going docs docs/_build/html
+.PHONY: docs docs-live docs-clean clean
+
+docs: docs-clean
+	HTTK_DOCS_BASE_URL=$(DOCS_BASE_URL) $(PYTHON) -m sphinx -E -a -b html -W --keep-going docs docs/_build/html
 
 docs-live:
-	sphinx-autobuild docs docs/_build/html
+	HTTK_DOCS_BASE_URL=$(DOCS_BASE_URL) sphinx-autobuild docs docs/_build/html
 
 docs-clean:
-	rm -rf docs/_build docs/reference/autoapi
-
+	rm -rf docs/_build
 
 clean: docs-clean
 	find . -name "*.pyc" -print0 | xargs -0 rm -f
 	find . -name "*~" -print0 | xargs -0 rm -f
 	find . -name "__pycache__" -print0 | xargs -0 rm -rf
-
-format:
-	$(PYTHON) -m ruff check src examples --select F401 --fix
-	$(PYTHON) -m isort src examples
-	$(PYTHON) -m black src examples
-
-format-check:
-	$(PYTHON) -m ruff check src examples
-	$(PYTHON) -m isort --check-only src examples
-	$(PYTHON) -m black --check src examples
-
-typecheck_pyright:
-	$(PYTHON) -m pyright
-
-typecheck:
-	$(PYTHON) -m mypy
-
-lint:
-	$(PYTHON) -m ruff check src examples

README.md

@@ -1,2 +1,6 @@
 # httk.github.io
-Documentation umbrella website
+
+The top-level documentation site for *httk₂*, published to the root of
+[docs.httk.org](https://docs.httk.org). It introduces the toolkit and links to each
+module; the detailed API reference for every module lives on its own per-module
+subsite (e.g. `docs.httk.org/httk-core/`, `docs.httk.org/httk-atomistic/`).

docs/_templates/autoapi/index.rst

@@ -0,0 +1,21 @@
+API Reference
+=============
+
+This page contains auto-generated API reference documentation [#f1]_.
+
+.. toctree::
+   :titlesonly:
+
+{% for page in pages %}
+   {% set state = namespace(has_rendered_parent=false) %}
+   {% for candidate in pages %}
+      {% if candidate.id != page.id and page.id.startswith(candidate.id ~ ".") %}
+         {% set state.has_rendered_parent = true %}
+      {% endif %}
+   {% endfor %}
+   {% if not state.has_rendered_parent %}
+   {{ page.include_path }}
+   {% endif %}
+{% endfor %}
+
+.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_

docs/conf.py

@@ -1,30 +1,46 @@
 import os
-import sys
 import warnings
 from datetime import date
 
 from sphinx.deprecation import RemovedInSphinx10Warning
 warnings.filterwarnings("ignore", category=RemovedInSphinx10Warning)
 
+# The notebooks are executed by a Jupyter kernel whose working directory is the
+# notebook's own folder, not this project root. Any relative PYTHONPATH entry (used
+# in local builds to point at a sibling module checkout, e.g. ../httk-atomistic/src)
+# would fail to resolve there, so normalize PYTHONPATH to absolute paths before the
+# kernel subprocess inherits it. Relative entries are resolved against the project
+# root (this conf.py's parent directory), which is where such a PYTHONPATH is meant
+# to be interpreted. This is a no-op in CI, where the modules are pip-installed and
+# PYTHONPATH is unset.
+_project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_pythonpath = os.environ.get("PYTHONPATH")
+if _pythonpath:
+    os.environ["PYTHONPATH"] = os.pathsep.join(
+        os.path.join(_project_root, entry) if entry and not os.path.isabs(entry) else entry
+        for entry in _pythonpath.split(os.pathsep)
+    )
+
 project = "httk₂"
 author = "The httk₂ AUTHORS"
 copyright = f"{date.today().year}, {author}"
 
 extensions = [
     # Core API docs
-    "sphinx.ext.autodoc",        # pull docstrings :contentReference[oaicite:4]{index=4}
-    "sphinx.ext.autosummary",    # API summary tables + stub gen :contentReference[oaicite:5]{index=5}
+    "sphinx.ext.autodoc",        # pull docstrings
+    "sphinx.ext.autosummary",    # API summary tables + stub gen
     "sphinx.ext.napoleon",       # Google/NumPy docstrings
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.extlinks",
     "sphinx.ext.mathjax",        # math rendering via MathJax
 
     # Nice-to-haves
     "sphinx_autodoc_typehints",
     "sphinx_copybutton",
 
     # Markdown + notebooks
-    "myst_nb",                   # .ipynb support :contentReference[oaicite:6]{index=6}
+    "myst_nb",                   # .ipynb support
 
     "autoapi.extension",
 ]
@@ -61,20 +77,33 @@
 ]
 myst_heading_anchors = 3
 
-# myst-nb config: don't execute notebooks during docs build by default
-nb_execution_mode = "off"
+# Execute the example notebooks as part of the (strict) docs build, so that an
+# example that no longer matches the current httk-core / httk-atomistic API fails
+# the build instead of silently going stale.
+nb_execution_mode = "force"
 
-html_theme = "furo"  # modern theme :contentReference[oaicite:7]{index=7}
+html_theme = "furo"
 html_theme_options = {
     "sidebar_hide_name": False,
     "navigation_with_keys": True,
 }
 
-# Optional: helpful external linking (edit as needed)
+# This top-level site now carries a full aggregate API reference built from the
+# submodule sources (see autoapi settings below), so cross-module references resolve
+# inside this site's own inventory rather than against the per-module subsites. The
+# DOCS_BASE_URL plumbing remains for the module directory's "go to the module's own
+# subsite" links. The base URL comes from the DOCS_BASE_URL Makefile variable
+# (exported as HTTK_DOCS_BASE_URL); the default below keeps bare sphinx invocations
+# working.
+_docs_base_url = os.environ.get("HTTK_DOCS_BASE_URL", "https://docs.httk.org")
+
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
 }
 
+# Plain "go to the module's docs" links, e.g. {moduledocs}`httk-core`.
+extlinks = {"moduledocs": (f"{_docs_base_url}/%s/", "%s documentation")}
+
 autoapi_options = [
        "members",
        "undoc-members",
@@ -85,16 +114,19 @@
 autoapi_root = "reference/autoapi"
 autoapi_ignore = []  # include everything
 
-autoapi_follow_symlinks = True
 autoapi_type = "python"
+# The merged httk namespace tree: src/httk/core and src/httk/atomistic are committed
+# symlinks into the two submodule checkouts, so AutoAPI parses both distributions as
+# a single PEP 420 httk root and cross-module references (httk.atomistic subclassing
+# httk.core objects) resolve internally.
 autoapi_dirs = ["../src/httk"]
-autoapi_add_toctree_entry = False
+autoapi_add_toctree_entry = True
 autoapi_keep_files = True
 autoapi_member_order = "bysource"
 autoapi_python_class_content = "module"  # docstring under class, not merged from __init__
 autoapi_python_use_implicit_namespaces = True
-autoapi_ignore = []
-#autoapi_template_dir = "_templates/autoapi"
+autoapi_follow_symlinks = True
+autoapi_template_dir = "_templates/autoapi"
 
 nitpicky = True
 nitpick_ignore = [
@@ -116,4 +148,3 @@ def skip_member(app, what, name, obj, skip, options):
 
 def setup(sphinx):
     sphinx.connect('autoapi-skip-member', skip_member)
-

docs/index.md

@@ -1,41 +1,65 @@
 # *httk₂*
 
-This is the aggregate documentation website for *httk₂*.
+*httk₂* is a modular high-throughput toolkit for computational materials science.
+It is not a single package: the `httk.*` import namespace is a PEP 420 native
+namespace shared by a set of independently developed and released module repositories.
+Installing the `httk` namespace by itself provides no functionality; you install the
+modules you need — starting with {moduledocs}`httk-core <httk-core>`, which supplies
+the shared primitives (type dispatch, datastreams, the `DataLoader`), and adding domain
+modules such as {moduledocs}`httk-atomistic <httk-atomistic>` for crystal-structure
+representations.
 
-*httk₂* is comprised of independent modules.
-There is a "standard set" that one can install to get started;
-and then additional modules can be added.
+This site is the top-level documentation for *httk₂*. It carries an aggregate
+{doc}`API reference <reference/index>` covering the published modules (pinned to the
+submodule revisions this site is built against), and each module additionally
+publishes its own subsite under [docs.httk.org](https://docs.httk.org); the
+{doc}`module directory <modules>` links to each one.
 
-## Install a standard set of modules
+```{admonition} Quick links
+:class: tip
+
+- **Module directory**: {doc}`modules` — every *httk₂* module and where its docs live.
+- **API reference**: {doc}`reference/index` — the aggregate reference for the published modules on this site.
+- **Example notebooks**: {doc}`notebooks/index` — runnable tours of the core and cross-module APIs.
+```
+
+## Install
+
+Preferably work in a Python virtual environment. Install {moduledocs}`httk-core <httk-core>`
+first — it brings in the `httk` namespace and the shared primitives:
 
-Preferably work in a Python virtual environment, then do:
 ```bash
-git clone https://github.com/httk/httk2
+git clone https://github.com/httk/httk-core
 cd httk-core
 python -m pip install -e .
 ```
 
-## Add a manually installed plugin module
+Then add whichever further modules you need, each the same way. For example, to add
+crystal-structure support from {moduledocs}`httk-atomistic <httk-atomistic>`:
 
-Use the same Python virual environment, and do, e.g.:
 ```bash
-git clone https://github.com/httk/httk-symgen
-cd httk-symgen
+git clone https://github.com/httk/httk-atomistic
+cd httk-atomistic
 python -m pip install -e .
 ```
 
+Each module is its own repository and can be installed independently; the shared
+`httk.*` namespace lets them compose at import time.
+
 ## Small usage example
 
 ```python
 from httk.core import subpackages
 
+# The httk.* subpackages discovered in the current environment.
 print(subpackages)
 ```
 
-## Documentation
 ```{toctree}
 :maxdepth: 2
+:hidden:
 
+modules
 reference/index
 notebooks/index
 ```

docs/modules.md

@@ -0,0 +1,78 @@
+# Module directory
+
+*httk₂* is delivered as a set of independent module repositories that share the
+`httk.*` namespace. Published modules are documented both here — in this site's
+aggregate {doc}`API reference <reference/index>`, pinned to the submodule revisions
+this site is built against — and on their own documentation subsite (both linked
+below); the remaining modules are under active development and do not yet publish
+docs.
+
+## Published modules
+
+### httk-core
+
+Shared core primitives for *httk₂*: type dispatch and the view/backend pattern,
+datastreams, and the `DataLoader` for reading httk dataset files. Every other module
+builds on it. Import path: `httk.core`.
+
+- API reference on this site: {doc}`httk.core </reference/autoapi/httk/core/index>`
+- Documentation subsite: {moduledocs}`httk-core`
+- Repository: <https://github.com/httk/httk-core>
+
+### httk-atomistic
+
+Crystal-structure representations — the `Structure` domain (Simple and primitive
+views, `Species`) built on the httk-core view/backend pattern. Import path:
+`httk.atomistic`.
+
+- API reference on this site: {doc}`httk.atomistic </reference/autoapi/httk/atomistic/index>`
+- Documentation subsite: {moduledocs}`httk-atomistic`
+- Repository: <https://github.com/httk/httk-atomistic>
+
+## In development
+
+These modules are planned or in progress; their APIs and documentation are not yet
+published.
+
+### httk-io
+
+File I/O for *httk₂*, including the CIF reader/writer stack, registered as httk-core
+loaders. Import path: `httk.io`.
+
+- Repository: <https://github.com/httk/httk-io>
+- Status: in development.
+
+### httk-symgen
+
+Symmetry-based crystal-structure generation. Import path: `httk.symgen`.
+
+- Repository: <https://github.com/httk/httk-symgen>
+- Status: in development.
+
+### httk-ml
+
+Tooling for machine-learned interatomic potentials. Import path: `httk.ml`.
+
+- Repository: <https://github.com/httk/httk-ml>
+- Status: in development.
+
+### httk-optimade
+
+OPTIMADE serving and client tooling. Import path: `httk.optimade`.
+
+- Repository: <https://github.com/httk/httk-optimade>
+- Status: in development.
+
+### httk-web
+
+The web and OPTIMADE serving stack. Import path: `httk.web`.
+
+- Repository: <https://github.com/httk/httk-web>
+- Status: in development.
+
+### httk-magnetism
+
+Magnetism workflows. Import path: `httk.magnetism`.
+
+- Repository: <https://github.com/httk/httk-magnetism>
+- Status: in development.