So, I wanted to add some API documentation to my project. Unfortunately, there are many competing standards/styles and many tools to generate HTML documentation.

Initially I chose pdoc, as it seems simple, does the job well and requires zero configuration. So far, so good. The problem is that is doesn't FULLY support ANY of the most popular docstring standards - ReStructuredText, Google, NumPy; instead, it uses its own style based on Markdown. I actually find it nice & clean, because:

• you don't need to specify variable/attribute/arg types if you already have type hints in your code

• you document instance/class variables right after they are declared (not in class docstring)

• similarly, you document _init__ constructor right after it is declared, not in the class docstring

The problem is that - besides pdoc itself - no one really recognizes its Markdown standard. It's not supported by PyCharm, pyment, pymend, nor by other tools.

However! According to Sphinx/Napoleon Example Google Style Python Docstrings, it is totally possible to use the Google docstrings style in a similar way - i.e, the 3 bullet points above would still work!

So, I could simply use Google style (which is a recognized standard) in a way I would use pdoc's Markdown. The only thing to make sure is not to use the Attributes: and Methods: sections in class docstring, as it would appear as duplicate in generated HTML. I would still use sections Args: Returns: Yields: and Raises: in function docstrings, where applicable.

And my commandline to run pdoc would be:

pdoc modulename -o docs --docformat google --no-show-source

What do you guys think?

PS. One minor downside of placing docstrings after variable declarations is that they do NOT become __doc__, as they do in the case of modules, classes and functions. So, these comments would not be discoverable programmatically (or interactively via help()). But I guess it doesn't matter that much...