Repository navigation
Scaffold Sphinx (Markdown/MyST) documentation - #93
Open
camillescottatwork wants to merge 3 commits into
Open
camillescottatwork wants to merge 3 commits into
camillescottatwork wants to merge 3 commits into
Conversation
Set up a Sphinx docs site authored in Markdown, laying out structure only (narrative pages are placeholders; API pages are generated from docstrings): - Add an optional `docs` Poetry group: sphinx, myst-parser, sphinx-autoapi, furo. - docs/ source tree with conf.py, Makefile/make.bat, a root index, and three sections — Architecture, User Guide, Reference. - Reference has an API subsection auto-generated by sphinx-autoapi (static analysis; never imports cheeto), excluding tests/, templates/, and the generated hippoapi/iamapi clients. - gitignore the build output (docs/_build/) and the generated API tree (docs/reference/api/). Build: `poetry install --with docs && sphinx-build -b html docs docs/_build/html`. Remaining build warnings are pre-existing source-docstring formatting issues, to be addressed with doc content later. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Diagrams are authored as ```{mermaid} blocks. Configured for client-side
rendering (mermaid_output_format = 'raw'), so HTML builds need no local
mermaid-cli/puppeteer and CI stays dependency-free.
mermaid_init_js picks mermaid's dark/default palette from furo's theme:
furo writes data-theme on <body> with values light/dark/auto, so 'auto'
is resolved against prefers-color-scheme. The palette is fixed at load,
so toggling the theme re-themes diagrams only on reload.
poetry.lock also picks up marker normalization from re-resolving with a
newer poetry; the only package change is sphinxcontrib-mermaid 1.2.3.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Replaces the Architecture placeholder with a diagram-led overview aimed at someone coming to the system fresh. Five pages: - architecture/index: framing (MongoDB is the source of truth; every external system is a projection out of it or an ingest into it), the layer stack, and the two recurring patterns that explain most of the codebase — read/reconcile/emit-commands and per-site dirty watermarks. - architecture/services: one section per external service (MongoDB, LDAP, Slurm, HiPPO, UC Davis IAM, puppet, email/Sympa) with module, transport, data-flow direction, and driver, plus the config sections. - architecture/scheduling: celery over RabbitMQ, the process types, the task/queue table, why worker concurrency is pinned to 1, and the puppet pull API. - architecture/database: the global-identity/per-site-config split and three erDiagrams (core identity, Slurm, storage), the operational collections, and the two silent beanie constraints that shape the models. - architecture/deployment: our specific deployment — the containerized hub on accounts with host-native mongo and rabbitmq, site workers on the three Slurm controllers, the multi-master LDAP pair, the puppet server's 60s pull into hiera-readable JSON, and the mount/secret contract per container. Also fills in the landing-page overview. Build is clean: the 44 remaining warnings are all pre-existing docstring formatting issues in the autoapi-generated reference/api tree. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Set up a Sphinx docs site authored in Markdown, laying out structure only (narrative pages are placeholders; API pages are generated from docstrings):
docsPoetry group: sphinx, myst-parser, sphinx-autoapi, furo.Build:
poetry install --with docs && sphinx-build -b html docs docs/_build/html. Remaining build warnings are pre-existing source-docstring formatting issues, to be addressed with doc content later.