Some Thoughts on the State of Python Package Documentation

Wow, the state of package documentation in Python is awful!

Maybe I’m just spoiled using languages like Java and Go that have excellent tooling for browsing package documentation of the standard library AND all available third-party packages. Their conventions pretty much boil down to this: it’s this way or the highway.

As far as I can tell, there’s nothing like this in the Python space. There are several browsers for the standard library docs, but I want to browse the docs of packages I install via Pip, and I’ve not found a canonical way to do so. There doesn’t seem to be a unified way in which package documentation is published. At one end you have vendors using the same doc generators as the standard library, which is fine. But at the other end, you’re left looking at massive Markdown files trying to find the package a particular symbol belongs (fix this please, Google).

This really is one area where Python shows it’s age. For a language that is popular and forward looking as it is, it feels like it missed that crucial time when the language designers took on the responsibility of standardising the way package documentation is published. Hope this is something that can be fixed. They’ve laid the foundation for this, by adding docstrings for example. They just need to make it easy to browse it (and no, pydoc does not do this. I’ve tried it).