[petsc-dev] User(s) manual sections field in manual pages?
jed at jedbrown.org
Mon Jun 17 13:50:27 CDT 2019
Patrick Sanan <patrick.sanan at gmail.com> writes:
> What are the options for incrementalism with this general approach? Does it
> make much sense to say "let's make sure the manual is online first, and
> then later we can update the man pages and tutorials?".
Note: The above "incrementalism" is different from my previous comment
about "incremental builds", which refers to being able to quickly update
docs after making a change, similar to what we get when building the
As for strategy, we have these primary forms of documentation:
* Users Manual
A lot of value here is in cross-references between the manual and man
pages. PETSc has a special pass where it creates links from to all
the man pages every time a keyword appears, including in listings.
I'd rather not be verbose about it in rst source as in
:c:func:`~.PetscScalar`. Also, the Firedrake manual (and I think
Sphinx as a whole) doesn't hyperlink keywords appearing in source.
So, for example, there is no link from CircleManifoldMesh to a man
PETSc's mapnameslatex.py script takes less than one second so this
isn't a performance issue.
* Developers Manual
This might be a good place to start because it is smaller and updated
less frequently. The same issues with auto cross-references apply.
* Manual pages
I need to learn a bit more about the numpydoc and breathe
implementations to be able to write a Sowing parser for it.
Easy in principle. We strip CHKERRQ, hyperlink all the functions, and
provide references from the man pages.
* HTML website-only documents (e.g., change logs, faq.html)
Pandoc seems to do fine out of the box with converting these to
rst/markdown (we can filter out the sidebar because it would be
generated by Sphinx). It's also the least interesting so I suggest
not prioritizing it.
> For instance, can we start by just generating stub .rst-formatted man
> pages, which include a link to the existing man pages?
I guess, but all the value is in cross-references. Also, I don't care
to have an rst-formatted representation appear in a file.
More information about the petsc-dev