<snip>
> The patchset contains the .rst sources which Sphinx uses to generate the
> html pages. These were first generated with the sphinx-apidoc utility
> and modified to provide a better look. The documentation just doesn't
> look that good without the modifications and there isn't enough
> configuration options to achieve that without manual changes to the .rst
> files. This introduces extra maintenance which involves adding new .rst
> files when a new Python module is added or changing the .rst structure
> if the Python directory/file structure is changed (moved, renamed
> files). This small maintenance burden is outweighed by the flexibility
> afforded by the ability to make manual changes to the .rst files.
>
> We can merge this patch when:
> 1. We agree on the approach with manually modifying the files.
> This approach is, in my opinion, much better than just generating the
> .rst files every time,

+1 for manually modifying .rst files. The .rst files are very simple,
and I think the added flexibility to change headers or tweak things as
needed is a big benefit over just auto-generating and not having as
much control. Additionally, if it just so happens that the
auto-generated file looks fine and the developer doesn't want to make
changes, they can still just generate it themselves and it fits right
in, so this approach still works with the other regardless.