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

[Lawrence Mitchell]

> On 17 Jun 2019, at 19:50, Jed Brown via petsc-dev <petsc-dev at mcs.anl.gov> wrote:

[...]
> 
> 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`.  

Yes, this is a disadvantage of OOTB sphinx (unless we've misconfigured it). You have to explicitly mark up the links in the long-form documentation that you would like to link. I guess we could do it after the fact, but have not done so. As a result, we're rather inconsistent about it. This is "fine" if you're reading the whole manual with a Python terminal up and running to check docstrings, but hardly seamless.

>  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

It ought, I suppose, be possible to write a plugin that adds links automagically to all keywords in formatted source, but I don't know the details of how these are written.

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

Would this be changing the format for man page docs to numpydoc? I don't know enough about the current setup one-way or another to know if 

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

This is certainly a disadvantage of our approach: docstrings as formatted in the python repl are ugly if they contain much linking (and/or maths). Having a setup that minimises the amount of noise in the text format is probably preferable.

Lawrence