Problem

pydoc-markdown is unmaintained (last supported Python version is 3.11, never left alpha stage). The author recommends switching to mkdocstrings.

This causes:

• Security alerts from outdated transitive dependencies (e.g. Black parser) — requires manual overrides (see apify-sdk-python#774)
• No Docusaurus-compatible output — we use pydoc-markdown only as an intermediate step, with custom JS glue code on top to produce Docusaurus-compatible format

Current setup

pydoc-markdown → Markdown → custom JS glue code → Docusaurus-compatible output

Options

1. Fork pydoc-markdown — maintain minimally, keep current tooling (short-term fix)
2. Switch to Sphinx / MkDocs — likely a no-go, neither produces Docusaurus-compatible output
3. Build a new tool — use Griffe (MkDocs parser) + custom renderer that outputs Docusaurus-compatible format directly, eliminating the JS glue code

Option 3 is the preferred long-term solution — a focused open-source tool that fills the gap in Python doc tooling for Docusaurus.

References

• pydoc-markdown repo disclaimer: "I don't find enough time to properly maintain and develop this project."
• Security override example: chore(deps): override vulnerable black transitive dependency apify-sdk-python#774