[petsc-dev] User(s) manual sections field in manual pages?
Jed Brown
jed at jedbrown.org
Wed Jun 12 11:18:11 CDT 2019
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.
More information about the petsc-dev
mailing list