docs: migrate documentation to themed Sphinx site - #3280
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. @@ Coverage Diff @@
## sam/sphinx-setup #3280 +/- ##
=================================================
Coverage 73.64% 73.65%
=================================================
Files 1068 1068
Lines 99443 99445 +2
Branches 9124 9125 +1
=================================================
+ Hits 73239 73249 +10
+ Misses 23604 23595 -9
- Partials 2600 2601 +1
Flags with carried forward coverage won't be shown. Click here to find out more.
... and 3 files with indirect coverage changes 🚀 New features to boost your workflow:
|
| bitrate | ||
| bringup | ||
| cancelled | ||
| cancelling |
There was a problem hiding this comment.
cancelling is British
canceling is American
There was a problem hiding this comment.
Therefore it is correct. :P
There was a problem hiding this comment.
Doesn't this file become irrelevant with Sphinx?
| ("py:class", "NDArray"), | ||
| ("py:class", "np.int8"), |
There was a problem hiding this comment.
These are incorrect. They're not using correct names, rather than them not being documented. If it's caused by a TYPE_CHECKING import or something, then it goes in the TODO(PY315) block below.
| checker. | ||
| """ | ||
|
|
||
| def brand(name, rawtext, text, lineno, inliner, options=None, content=None): |
There was a problem hiding this comment.
Any reason to drop this? I was trying to make the spelling list only contain genuine words that are missing from the builtin dictionary.
| def shorten_long_class_signatures(app, what, name, obj, options, signature, return_annotation): | ||
| """Collapse generated constructors that would overwhelm the API page.""" | ||
| if what == "class" and signature and len(signature) > 120: | ||
| return "(...)", return_annotation | ||
| return None |
There was a problem hiding this comment.
The truncated part could include important information for a developer. We should instead evaluate on a case-by-case basis and remove irrelevant parts from the signature (there's parameters to adjust this).
| ("py:class", "dimos.types.timestamped.PRIMARY"), | ||
| ("py:class", "dimos.types.timestamped.SECONDARY"), | ||
| ("py:class", "dimos.utils.reactive.T"), | ||
| ("py:class", "dimos.utils.reactive.LatestReader"), |
There was a problem hiding this comment.
This one is not a TypeVar, seems like it should be documented.
| ("py:class", "np.int8"), | ||
| ("py:class", "open3d.cuda.pybind.geometry.PointCloud"), | ||
| ("py:class", "open3d.cuda.pybind.t.geometry.PointCloud"), | ||
| # Types referenced by documented signatures but not part of this API slice. |
There was a problem hiding this comment.
Meaning this is a TODO to fix later?
| # A prose return condition in align_timestamped's Google-style docstring. | ||
| ("py:class", "If single secondary observable"), |
| ("py:class", "JointState"), | ||
| # A prose return condition in align_timestamped's Google-style docstring. | ||
| ("py:class", "If single secondary observable"), | ||
| # Supporting memory and visualization types outside the documented slice. |
There was a problem hiding this comment.
Also a TODO?
My approach was to just add everything that was referenced.
3 participants
Stack
sam/sphinx-setup).Problem
Sam's PR establishes the Sphinx structure, but the documentation still needs usable
navigation, API cross-references, code-block references, and a production-quality theme.
The team also wants to keep authoring prose in Markdown and retain the Mintlify build
during the Sphinx transition.
Solution
docs/api.rstfor the autodoc-heavy generated API referenceand visual treatment with the hosted Dimensional docs
sphinx-designcardsdocs-old/, including local preview, validation,and static export on Node 22
docs-old/from the canonical documentation link resolver.rstto.mdDocumentation prose was kept unchanged wherever possible; changes are primarily format
conversion, reference activation, navigation, and presentation.
How to test
Sphinx
Open http://localhost:8000/.
Mintlify fallback
Use Node 22:
cd docs-old npm ci npm run validate npm run build npm run devValidation
57 passedindimos/utils/docs/test_doclinks.pygit diff --checkThe spelling builder remains enabled in CI, where the
en_USEnchant dictionary isinstalled explicitly.
AI assistance
Codex with GPT-5 was used extensively for mechanical conversion, Sphinx reference
activation, theme and navigation work, diagnosis, and validation. The changes were
directed and reviewed interactively by the author.
Checklist