<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Apr 29, 2024 at 9:49 AM Jeremy Spewock <<a href="mailto:jspewock@iol.unh.edu">jspewock@iol.unh.edu</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><snip><br>
> The patchset contains the .rst sources which Sphinx uses to generate the<br>
> html pages. These were first generated with the sphinx-apidoc utility<br>
> and modified to provide a better look. The documentation just doesn't<br>
> look that good without the modifications and there isn't enough<br>
> configuration options to achieve that without manual changes to the .rst<br>
> files. This introduces extra maintenance which involves adding new .rst<br>
> files when a new Python module is added or changing the .rst structure<br>
> if the Python directory/file structure is changed (moved, renamed<br>
> files). This small maintenance burden is outweighed by the flexibility<br>
> afforded by the ability to make manual changes to the .rst files.<br>
><br>
> We can merge this patch when:<br>
> 1. We agree on the approach with manually modifying the files.<br>
> This approach is, in my opinion, much better than just generating the<br>
> .rst files every time,<br>
<br>
+1 for manually modifying .rst files. The .rst files are very simple,<br>
and I think the added flexibility to change headers or tweak things as<br>
needed is a big benefit over just auto-generating and not having as<br>
much control. Additionally, if it just so happens that the<br>
auto-generated file looks fine and the developer doesn't want to make<br>
changes, they can still just generate it themselves and it fits right<br>
in, so this approach still works with the other regardless.<br>
<br></blockquote><div>+1 </div></div></div>