Rewrite documentation and simplify docs build pipeline - #92
Merged
olivhoenen merged 11 commits intoSep 1, 2026
Conversation
Yannicked
marked this pull request as ready for review
July 10, 2026 12:45
Yannicked
requested review from
SimonPinches,
maarten-ic,
olivhoenen and
prasad-sawantdesai
as code owners
July 10, 2026 12:45
| # Installation | ||
|
|
||
| SimDB is distributed as the `imas-simdb` Python package and requires | ||
| **Python 3.11 or newer**. |
Contributor
There was a problem hiding this comment.
pyproject.toml says >=3.8 ...?
| ## Quickstart | ||
|
|
||
| Install SimDB (requires Python 3.11+): | ||
| SimDB requires Python 3.11 or newer. |
Contributor
There was a problem hiding this comment.
pyproject.toml says >=3.8 ...?
Contributor
There was a problem hiding this comment.
@Yannicked can you make this description more uniform w.r.t pyproject deps (or vice-versa) and fix the conflicts please?
Collaborator
Author
There was a problem hiding this comment.
I've changed it to require python 3.11, is that okay?
Contributor
Content accuracy:
- Correct PostgreSQL config keys (user/db_name, not username/database/name)
in the Docker, PostgreSQL, and server-configuration pages.
- Docker guide: fix the docker-compose-pyver.yml usage description.
- query-operators: agt/age/alt/ale are range operators (min/max), available
locally and remotely, not "remote only".
- server-configuration: document copy_files, copy_ids, user_upload_folder,
the Keycloak auth type, and comma-separated authentication.type.
- rest-api: reconcile endpoint list (namespaces vs top-level routes) and add
an "API versioning" section explaining the scheme and the requirement that
every endpoint be exposed on each new version; add v1.3 (in development).
- connect-to-iter: reword the unsupported "pre-populates iter remote" claim
and use REQUESTS_CA_BUNDLE (the variable actually honored).
New content:
- Add how-to/capture-provenance for the simdb provenance command.
Layout/build:
- Add an "edit this page" link (content.action.edit + edit_uri).
- Standardize forward-nav footers ("Next steps") and step-heading style.
- Wire the orphaned multi-instance-deployment page into the operate-server
toctree (renamed run-multiple-instances.md).
- Add _static/.gitkeep so html_static_path exists on a fresh checkout.
The docs build emitted ~90 warnings, all from the auto-generated Python API reference. Fix them at the source where possible and configure away the irreducible third-party noise: - Set autodoc_inherit_docstrings = False so autodoc does not pull SQLAlchemy / Cerberus base-class docstrings (full of :term:/:ref:/:paramref: roles that do not resolve here) into wrapper methods that lack their own docstring. - Convert the Epytext (@param/@return/@raise) docstrings that produced docutils "unexpected indentation" errors to Sphinx field syntax (config.Config, RemoteAPI.get, imas.utils, LdapAuthenticator). - Clear stale generated python-api/*.rst before running apidoc so a deleted/renamed module cannot leave an un-importable orphan page. - suppress_warnings for the remaining structural noise (duplicate apidoc targets, a Cerberus types_mapping repr that is not valid Python), and a narrow logging filter for sphinx-immaterial's untyped "parameter name does not match" warning on Pydantic/Cerberus-decorated members. Broken authored cross-references (myst.xref_missing) are not suppressed and still fail as before. Build now completes with zero warnings.
remove mention of SIMDB_REQUESTS_CA_BUNDLE anywhere, it's a distraction.
Yannicked
force-pushed
the
feature/rework-docs
branch
from
September 1, 2026 10:21
151d5d5 to
26fc4ab
Compare
olivhoenen
approved these changes
Sep 1, 2026
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
4 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.
https://simdb--92.org.readthedocs.build/en/92/