API pages and inventory · Issue #1220 · Python-Markdown/markdown (original) (raw)

Hello! Thanks a lot for Python Markdown, we'd do nothing without it 🙂

Would you be interested in providing API pages in your documentation, as well as a consumable objects inventory?
I'm willing to send a PR if that's something you'd like. Personally, I'd love to get automatic cross-refs to your markdown objects in my own API documentation pages.

The idea is to use the mkdocstrings plugin (disclaimer: I'm the author) to inject some code reference into your pages.
When using mkdocstrings, every object that is rendered is added to an inventory file, objects.inv, and that file is added to the final site. Users can then load that inventory when rendering their docs, so that annotations like Markdown will automatically link to the Markdown class in your API documentation.

I tried it locally, and since it seems you're using pure Markdown docstring, the result is not so bad:

If you find this useful and would like to proceed, I'll need some information like: what is considered public and therefore should be rendered? Is it just the objects that can be imported from markdown directly? Or more objects in deeper submodules?

If you find no interest in this, or don't want to proceed for other reasons (I see for example that you already provide a manually written reference page), that's totally fine, I won't push for it 🙂