[petsc-dev] User(s) manual sections field in manual pages?

[Jed Brown]

Patrick Sanan <patrick.sanan at gmail.com> writes:

> It'd be huge if pandoc can do the heavy lifting of converting the manual to
> a human-readable-yet-html-renderable format. As a stopgap, particularly
> ornery sections of latex could perhaps be compiled as standalone pdfs and
> included.
>
> .rst seems like a reasonably safe choice. 

It's nicely extensible, just irritatingly verbose for common uses.

> So many projects use it (including the linux kernel, moving away from
> bookdown, says wikipedia) 

They switched from Docbook to rst.

  https://www.kernel.org/doc/html/latest/

They have their own preprocessor for C source comments (similar but not
identical to javadoc).  The resulting API documentation is basic, but
this isn't really a limitation of Sphinx:

  https://www.kernel.org/doc/html/latest/core-api/mm-api.html#c.filemap_range_has_page

> that it seems unlikely to go away any time soon. What firedrake has
> looks pretty gorgeous.

Yes, though I'm concerned about how to render the API documentation.  We
currently have a separate page for each function.  Deep links are
important and if we put entire sections on one page, it'll be a heavy page.

> An advantage of a parser for the sowing man pages is that it could also be
> used to check/enforce rules, like checking the symmetry of the .seealso
> graph (Note again this man-page walking script that Scott already wrote:
> https://bitbucket.org/petsc/petsc/commits/53db19705a7bf2d1838cb64c11c1e5ab5997e81d
> )

I don't think the symmetric graph should be maintained manually.
Instead, we should have man pages include "Referenced by".

Sphinx supports a search dialog, but it would be a lot nicer if it would
autocomplete.