So, to take an example, here's the documentation for a library I maintain: http://webcolors.readthedocs.io/ http://webcolors.readthedocs.io/ Once upon a time,

So, to take an example, here's the documentation for a library I maintain: http://webcolors.readthedocs.io/ http://webcolors.readthedocs.io/ Once upon a time, the entire library's documentation was generated from docstrings in the code, but the library very quickly outgrew that as I needed to do things like: * How to install the library and how to run the tests * Properly explain the web color model and the history of how it's been implemented in the specifications * Properly explain how the various ways to specify colors get represented as Python types * Explain how Python 2/3 compatibility is handled etc., etc. There are a ton of things that don't naturally attach to just one function or class, but need to be in the documentation. The hacky compromise solution is a module-level docstring, but now people who want to read source have to scroll through a huge amount of stuff before they see a single line of actual code. So I'm going to stay far away from auto-generated documentation and "just put it in comments/docstring/etc." for the foreseeable future.