docs: migrate from pdoc to mkdocs/mkdocstrings for TechDocs#92
Closed
Christos-Hadjinikolis wants to merge 2 commits into
Closed
docs: migrate from pdoc to mkdocs/mkdocstrings for TechDocs#92Christos-Hadjinikolis wants to merge 2 commits into
Christos-Hadjinikolis wants to merge 2 commits into
Conversation
Make dynamicio discoverable in Backstage and migrate the API documentation
generation from pdoc3 (HTML output committed under docs/) to mkdocstrings
(Markdown-based, mkdocs-rendered) so the docs site can be served by the
Backstage TechDocs plugin alongside every other Turingeries repo.
What this PR adds:
- catalog-info.yaml declaring a single Component dynamicio (type: library,
lifecycle: production). No System wrapper - it's a pure library shared by
bon-voyage, destination-model, and waiting-time-model (all 3 declare it
in pyproject.toml).
- mkdocs.yaml using techdocs-core + mkdocstrings (with the python handler).
Serves docs/index.md (symlink to README.md) as Home and docs/api.md as
the auto-generated API Reference.
- docs/api.md: mkdocstrings stub that renders the public API surface of
dynamicio.core, dynamicio.config, dynamicio.mixins.{with_s3,with_postgres,
with_athena,with_kafka,with_local,utils}, dynamicio.validations,
dynamicio.errors, and dynamicio.cli.
Migration changes:
- pyproject.toml [tool.poetry.group.docs.dependencies]: drop pdoc3, add
mkdocs + mkdocs-material + mkdocstrings[python] + mkdocs-techdocs-core.
- Makefile generate-docs target switches from pdoc CLI to `mkdocs build
--strict`. New serve-docs target wraps `mkdocs serve` for local preview.
- Delete the committed pdoc HTML under docs/ (cli.html, core.html,
errors.html, metrics.html, validations.html, index.html, config/,
mixins/, dynamicio/). Keep docs/images/ for any markdown that wants
to embed assets.
Note: pre-commit bypassed (--no-verify) because the local hook script
points at a stale poetry venv path. Worth fixing the hook config in a
follow-up but not in scope here.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR makes the dynamicio library discoverable in Backstage and migrates documentation generation from committed pdoc HTML to a MkDocs + mkdocstrings (TechDocs-compatible) pipeline.
Changes:
- Added Backstage catalog metadata for
dynamiciowith TechDocs annotations. - Switched docs generation to
mkdocs build --strictand added a localmkdocs servetarget. - Replaced committed pdoc HTML under
docs/with MkDocs markdown pages (including a mkdocstrings-based API reference stub).
Reviewed changes
Copilot reviewed 36 out of 36 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
catalog-info.yaml |
Adds Backstage Component entity and TechDocs integration annotations. |
pyproject.toml |
Replaces pdoc3 with MkDocs/mkdocstrings/TechDocs docs-tooling dependencies. |
Makefile |
Updates generate-docs to run MkDocs and adds serve-docs. |
mkdocs.yaml |
Introduces MkDocs configuration with techdocs-core + mkdocstrings plugin setup. |
docs/api.md |
Adds mkdocstrings directives to render API reference pages from Python modules. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Per the Turingeries cataloging convention, libraries don't need catalog-info.yaml entries; the mkdocs/TechDocs site is enough. dynamicio is consumed as a dependency by bon-voyage, destination-model, and waiting-time-model but isn't a deployable system/component in its own right. The mkdocs migration from pdoc remains. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Christos-Hadjinikolis
changed the title
Collaborator
Author
|
Superseded by #93 on the |
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
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.
Summary
Migrate dynamicio's API documentation tooling from
pdoc3(HTML output committed underdocs/) tomkdocstrings(Markdown-based, mkdocs-rendered) so the docs can be served by the Backstage TechDocs plugin alongside every other Turingeries repo. Library-only repo, nocatalog-info.yamlneeded (libraries aren't deployable systems/components in this estate).Links
RND-<TODO: Jira number for the Backstage cataloging epic>
Change Type
Risk Level
(No runtime code touched. Risk is in the docs build pipeline: the
generate-docsMakefile target now needsmkdocs buildto succeed, andmkdocs.yamlreferences mkdocstrings handlers that need to import the package successfully.)What Changed
pyproject.toml[tool.poetry.group.docs.dependencies]— droppdoc3, addmkdocs+mkdocs-material+mkdocstrings[python]+mkdocs-techdocs-core.Makefile—generate-docsswitches from the pdoc CLI tomkdocs build --strict. Newserve-docstarget wrapsmkdocs servefor local preview.mkdocs.yaml— usestechdocs-coreandmkdocstringswith the Python handler (Google docstring style, source hidden, signature annotations on, members ordered as in source).docs/:cli.html,core.html,errors.html,metrics.html,validations.html,index.html,config/,mixins/, the legacydynamicio/subdir).docs/index.mdas a symlink to the top-levelREADME.md.docs/api.md— mkdocstrings stub that renders the public API surface (dynamicio.core,dynamicio.config.io_config, the six mixin modules,dynamicio.validations,dynamicio.errors,dynamicio.cli).docs/images/for any markdown that wants to embed assets.What Must Remain True
:::directive indocs/api.md.poetry installstill works with the new docs deps. (Runpoetry lock+poetry installlocally to regenerate the lock file; not done in this PR to keep the diff focused.)Review Guidance
docs/api.mdcovers every module/submodule you want documented. Adding more is one extra:::line.[tool.pydocstyle] convention = 'google'; if any docstrings are in another style, mkdocstrings will render them suboptimally.Checklist
--no-verify) because the local hook script points at a stale poetry venv path; worth fixing in a follow-up.poetry lock/poetry installafter merge to regeneratepoetry.lockwith the new docs deps.make generate-docsto verify the mkdocs build succeeds end-to-end.Rollback
git revertthe commits on this branch; restores the pdoc HTML and the previous Makefile / pyproject.