I think reference documentation taken from docstrings can be useful in some situations. It's also way easier to keep accurate in my experience. All of which isn't to say that it is or should be the complete documentation. This is why the factoring I propose has documentation generated from multiple sources, including static text, and potentially text in different formatters. So a document extractor looks at the source and gets docstrings and maybe comments and whatnot. Another looks for .txt files, and maybe renders them via some configured markup (reST, Markdown, etc). Another might just pass through already-written HTML. This factoring doesn't propose any one right way to get the content, or even that one project will use just one content generator.