diff --git a/README.md b/README.md index bb00ad87..c041a46f 100644 --- a/README.md +++ b/README.md @@ -740,12 +740,15 @@ _Task runners and software build tools. If you're looking for Python packaging/b _Libraries for generating project documentation._ -- [sphinx](https://github.com/sphinx-doc/sphinx) - Python documentation generator. - - [awesome-sphinxdoc](https://github.com/ygzgxyz/awesome-sphinxdoc) -- [mkdocs-material](https://github.com/squidfunk/mkdocs-material) - A documentation framework and Material Design theme built on MkDocs. -- [diagrams](https://github.com/mingrammer/diagrams) - Diagram as Code. -- [pdoc](https://github.com/mitmproxy/pdoc) - Auto-generates API documentation for Python projects. -- [zensical](https://github.com/zensical/zensical) - A modern static site generator for technical documentation. +- Site Generators + - [sphinx](https://github.com/sphinx-doc/sphinx) - A Python documentation generator. + - [awesome-sphinxdoc](https://github.com/ygzgxyz/awesome-sphinxdoc) + - [mkdocs-material](https://github.com/squidfunk/mkdocs-material) - A documentation framework and Material Design theme built on MkDocs. + - [zensical](https://github.com/zensical/zensical) - A static site generator for documentation, from the Material for MkDocs team. +- API Reference + - [pdoc](https://github.com/mitmproxy/pdoc) - Auto-generates API documentation for Python projects. +- Diagrams + - [diagrams](https://github.com/mingrammer/diagrams) - Diagrams as code for prototyping cloud system architectures. **DevOps** diff --git a/docs/audit-logs.md b/docs/audit-logs.md index 14c6713e..31b8df60 100644 --- a/docs/audit-logs.md +++ b/docs/audit-logs.md @@ -28,7 +28,7 @@ Display names follow the canonical PyPI package name. These entries keep a diffe Entries admitted despite the Stable quality requirement, by maintainer decision: -- zensical -- admitted 2026-08-23 at version 0.0.57, PyPI classifier `Development Status :: 3 - Alpha`, with no 1.0 target announced. Admitted as a challenger displacing mkdocs because the Documentation section was carrying a dying upstream: the Material for MkDocs team's announcement of 2025-11-05 put Material into maintenance mode for twelve months and called MkDocs itself unmaintained since 2024-08 and a supply chain risk. Re-check when 1.0 lands. +- zensical -- admitted 2026-08-23 at version 0.0.57, PyPI classifier `Development Status :: 3 - Alpha`, with no 1.0 target announced. Admitted as a challenger displacing mkdocs because the Documentation section was carrying a dying upstream: the Material for MkDocs team's announcement of 2025-11-05 put Material into maintenance mode for twelve months and called MkDocs itself unmaintained since 2024-08 and a supply chain risk. Re-checked 2026-11-08 in the Documentation audit at 0.1.0, PyPI classifier `Development Status :: 4 - Beta`, 2,234,473 downloads/month on ClickPy: kept. Material for MkDocs moved its end of life to 2027-05-05 and names zensical its maintained successor, so re-check both slots then, or when 1.0 lands. - openviking -- admitted 2026-08-25 (PR #3302) at version 0.4.16, PyPI classifier `Development Status :: 3 - Alpha`, with a README that said "OpenViking is still in its early stages". Admitted as a Data Layer challenger because the adoption is real: 459,446 downloads/month on pypistats (mirror-excluded) on 2026-08-24, and releases every few days. Re-check when 1.0 lands. - claude-agent-sdk -- kept 2026-10-01 in the AI and Agents audit at version 0.2.163, PyPI classifier `Development Status :: 3 - Alpha`. Kept as a Vendor Agent SDKs obvious choice because the adoption is real: 30,033,689 downloads/month on ClickPy on 2026-10-01, up from 1.2M in March 2026 on pypistats. Re-check when 1.0 lands. - uv-audit -- kept 2026-08-16 as a Supply Chain Security entry, recorded 2026-10-02. uv itself prints "`uv audit` is experimental and may change without warning". Kept because it is part of uv, the obvious package manager. Re-check when uv drops the experimental notice. diff --git a/website/data/category_intros/documentation.md b/website/data/category_intros/documentation.md index c0fad335..08754517 100644 --- a/website/data/category_intros/documentation.md +++ b/website/data/category_intros/documentation.md @@ -5,8 +5,8 @@ How to choose: - API docs straight from docstrings, with no configuration: pdoc - Handwritten docs plus an API reference, as HTML, PDF, and more: Sphinx - A searchable Markdown site, with no HTML, CSS, or JavaScript to learn: Material for MkDocs -- Architecture diagrams as code, kept in version control: Diagrams - A Material for MkDocs site, new or existing, on its team's own generator: Zensical +- Architecture diagrams as code, kept in version control: Diagrams pdoc [aims to do one thing and do it well](https://pdoc.dev/docs/pdoc.html#what-is-pdoc): API documentation that follows your module hierarchy, with no configuration. Docstrings are Markdown, and it understands Google and numpydoc styles too. Run `pdoc ./demo.py` or `pdoc my_module_name` for a [preview in your browser that reloads](https://pdoc.dev/docs/pdoc.html#quickstart) when you edit the code, then `pdoc ./demo.py -o ./docs` to export the HTML. Its output is self-contained HTML, and for substantially more complex documentation needs, [pdoc's docs recommend Sphinx](https://pdoc.dev/docs/pdoc.html#limitations).