Adopt a shared specification for api structure

[tristanlatr]

Hello there.

In a general effort to make the python api documentation ecosystem a bit more standardized, I think documentation generators should adopt a common standard for serializable api structure of a collection of modules. This will serve the python libraries developers at large since the separation in between the backend parser and the front end renderer would become standard accros generators. This way developers will be able to choose their preferred backend/frontend combination that fits their package the best.

Currently mkdocstring is working with this infrastructure since the backend can be changed.
Whereas pydoctor (but I’ll definitely work on that in the coming months).
The sphinx-apidocs project is also pretty close.

These three packages covers the API documentation needs for more or less any project: using Sphinx, Mkdocs or simply standalone API.

So I wanted to start this discussion with maintainers of these three packages to think and settle on a common standard.
The docspec standard exists but I believe it needs to be extended a little bit to fit everyone usage.

Tell me what’s you think :)

[pawamoy]

Hey @tristanlatr!

Yes, it's a good idea to share about this between maintainers 🙂 Thanks for reaching out!

Indeed, the docspec specification is too limited for Griffe right now. I think the most important thing to standardize is the serialized data, as you mentioned it. It must provide all the necessary information to inflate/hydrate back into any language. Then each language and respective library can choose to provide more methods, or different methods.

Griffe's own API is serialized and exposed here: https://mkdocstrings.github.io/griffe/griffe.json. It's updated everytime I deploy its documentation. If others want to share a similar JSON file, we can start comparing and maybe suggest incremental standardizations 🙂

Due to the discussion nature of this issue, I'll convert it to a discussion.