On Mon, Apr 29, 2024 at 9:49 AM Jeremy Spewock <jspew...@iol.unh.edu> wrote:
> <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. > > +1
