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

[Jed Brown]

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
library.


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
  page.

  https://www.firedrakeproject.org/extruded-meshes.html#generating-extruded-meshes-in-firedrake

  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.

* Examples

  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.