On Mon, Apr 29, 2024 at 9:49 AM Jeremy Spewock <jspewock@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