(I initially drafted this in Discussions, but I ended moving here. Happy to move it there if required)

Context

After digging a bit in this project and reading some of the issues, I found some things that could be improved regarding the documentation:

• The whole API and usage examples live in a single README.md making harder to read.
• Some classes and methods are documented but not rendered in any documentation site. Someone also #848 that current docstrings don't follow any standard in order to be rendered properly.
• Documentation is incomplete and could be extended. See issues #499 #528

Proposals

Documentation language

Current README uses markdown to render the contet. The obvious choice would be use markdown, but I just wanted to mention that rewriting to RST (RestructuredText) it's also an option.

Documentation Generator

There are many options to generate documentation but I'm only listing here the most suitable options for Python.

mkdocs

This the default choice for many projects. This tutorial explains very well how to use with Python.

Pros:

• Supports Markdown
• Supports Google-Style Docstrings, NumPy Docstring Standard and Sphinx Docstring Format.
• Has many plugins and lot of community around it.

Sphinx

This is the classic way to host Python docs, typicall using RST and hosted in readthedocs.

Pros:

• Supports RST and Markdown (with a plugin).
• Classic player for Open Source Python projects.

nanoc

This is what the official Prometheus documentation uses to generate its documentation.

Pros:

• It documentation system used by Prometheus.

Cons:

• It doesn't generate documentation from Python docstrings.
• Community and adoption is lower compared to other projects.

Hosting

Where the documentation should live is also relevant for this discussion.

GitHub Pages

Is it the recommended way when using mkdocs. It works creating a branch/repo that will publish automatically changes when new docs are pushed to main.

Read the Docs

Is it a very common way to host documentation pages of Python projects. It works configuring a hook in repository. Readthedocs will pull the changes and publish to the configured site.

prometheus.io

This approach requires using prometheus docs along with nanoc to host the documentation. It would make everything consistent as all the docs are in the same website and it would open the door to other client libraries to host documentation there. The repo could pull changes from client_python/docs. However this would require manually update the git submodule everytime docs are changed in client_python.

Alternatively, we could create a subdomain (https://prometheus.io/docs/python) that points to a different hosting that the Prometheus project.

Do nothing

Making the README bigger every time that new features are add and leave docs and classes undocumented.

My way to go would be:

• markdown
• sphinx docstrings
• mkdocs + custom template similar to Prometheus
• hosting in github pages / readthedocs with a custom subdomain in prometheus.io

cc @csmarchbanks (maybe @roidelapluie ?)

Hi there, I find writing documentation in Markdown more pleasant than writing it in RST. However, docstring in Python often follows RST format, either in Numpy or Google docstring style. I tried to use MyST before, but I found that it didn't work that well with Sphinx, as there are some bugs here and there. So what we end up using is just writing our docs in RST.

Disclaimer: I tried myst out a year ago, and that was the experience then, not entirely sure about now 😊

With Sphinx, one nice thing is its' feature-rich ecosystem. Furo is a pretty neat theme for documentation, sphinx-design also has a lot of pretty nice stuff there. One drawback is that by using Sphinx, you are tied to its ecosystem, meaning that we don't have a lot of flexibility.

I also like the route of building docs in Gatbsy or any other static site generator (Hugo, Gatbsy, etc.), as we have full control of how the docs look like. We probably will just have to find a docstring parser in that case.

With readthedocs I find that it is pretty easy to set up as well. Personally, I haven't worked with mkdocs b4, so I'm not entirely sure about the UX.

A quick example for how the RST docstring might look like: link here

If possible for docs I would prefer markdown at least for the non-docstring docs as we use markdown for docs in many other places across Prometheus. For docstrings I don't have a strong preference between Google and Numpy style docstrings, I would prefer to avoid the :param blah style as I find it much less readable in the code.

Where to host the docs is an interesting question, possibly a question for the dev summit at PromCon in a couple of weeks. Today I don't think we host any client-specific documentation on prometheus.io, instead using godoc and docs.rs for the official go and rust libraries. For that reason I am tempted to start with readthedocs and we could add a custom domain later if we want. What do you think of that idea?

Thanks for the input @csmarchbanks. Any preference between mkdocs or sphinx?

No strong preference, happy with whichever you want to use, which sounded like mkdocs.

Hi @marctc, I have opened #851 and #852 as an initial starting point for the docs improvement effort. I would love to hear more feedback on this two PR.

cc @csmarchbanks

Another question. Is there a formatter tool that prometheus_client is currently using?

We use flake8 today, it is configured in tox.ini.

Hey, I plan to revamp this work, sorry for the delay. Speaking with @fstab, he mentioned that used hugo for the docs. This how it renders https://prometheus.github.io/client_java/.

I'd like to converge on the tooling and use the same. Do you have any thoughts @csmarchbanks?

Thanks for revamping the work! I was just thinking of reaching out to you.

I like the plan to use the same tooling, I haven't look in depth at what they have done, but 👍 on the idea.

I kept notes how I set the client_java docs up at the bottom of the README https://github.com/prometheus/client_java/blob/main/docs/README.md#update-geekdocs

Docs are deployed via Github action when merged to main.

Thanks @fstab, i think with the pointers you provided we would be able to have a documentation in place in no time!