The Python code documentation systems available are... scattered. And not very good. And definitely not well maintained. Lately when I see a hard problem that isn't getting solved well, I like to think of smaller problems that maybe could be solved.

Here's a rough outline of what I think a Python documentation generation system should look like:

• It should be distribution oriented, not module oriented. That means it works on a package that gets distributed, not on specific Python modules. So no separate command-line tools, and options should be in setup.cfg.
• Extraction should be pluggable in some form. The extraction should produce something HTML-like, except without any attention paid to styling. There may be several extractors; e.g., one to format source code, another to create graphs of relations, another to extract docstrings, another to render the static files. Lots of people have written this part, and it's hard, and it will keep being rewritten for a while.
• Then a multi-stage rendering system.
  • One stage is resolving links between documents. So I should be able to link to paste.fixture.TestApp and have it work, without having to worry what file that documentation is going to appear in (or if it is combined with other documentation in a file and referenced with an anchor). A fancier system would allow inter-project linking, but this is much more complex.
  • Producing indexes and navigation (table-of-content style) is another stage. The navigation that is presented on every page should probably just be maintained manually.
  • Applying a template is a final stage. Many systems have an essentially hardcoded template, or hidden. The interior content is harder to customize in general, but simply allowing the wrapper to be easily customized would be really helpful.

I prefer a system based on static publishing because it's easy to maintain, and works well with systems like SourceForge. But in theory pieces of this system could be dynamic.

This bears some similarity to how PythonDoc is laid out, but it hasn't been clear to me how that project fits all these pieces together. Also some portions don't seem pluggable; e.g., it prefers its own markup. But that might be a misperception.