> On 17 Jun 2019, at 19:50, Jed Brown via petsc-dev <petsc-dev@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
Re: [petsc-dev] User(s) manual sections field in manual pages?
Lawrence Mitchell via petsc-dev Mon, 17 Jun 2019 12:27:37 -0700
- Re: [petsc-dev] User(s) manual sectio... Jed Brown via petsc-dev
- Re: [petsc-dev] User(s) manual se... Smith, Barry F. via petsc-dev
- Re: [petsc-dev] User(s) manua... Patrick Sanan via petsc-dev
- Re: [petsc-dev] User(s) manua... Matthew Knepley via petsc-dev
- Re: [petsc-dev] User(s) manua... Jed Brown via petsc-dev
- Re: [petsc-dev] User(s) manual se... Jed Brown via petsc-dev
- Re: [petsc-dev] User(s) manua... Scott Kruger via petsc-dev
- Re: [petsc-dev] User(s) manua... Jed Brown via petsc-dev
- Re: [petsc-dev] User(s) manua... Jed Brown via petsc-dev
- Re: [petsc-dev] User(s) manua... Jed Brown via petsc-dev
- Re: [petsc-dev] User(s) manua... Lawrence Mitchell via petsc-dev
- Re: [petsc-dev] User(s) manua... Jed Brown via petsc-dev
- Re: [petsc-dev] User(s) manua... Jed Brown via petsc-dev
- Re: [petsc-dev] User(s) manual sections fi... Smith, Barry F. via petsc-dev