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

[Jed Brown]

Jed Brown via petsc-dev <petsc-dev at mcs.anl.gov> writes:

> Scott Kruger <kruger at txcorp.com> writes:
>
>>>> 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/
>>
>> Is that the default C autodoc extension, or hawkmoth?
>>
>> https://hawkmoth.readthedocs.io/en/latest/extension.html
>
> There is no reference to hawkmoth in the repository.  At a glance, it
> looks like Hawkmoth exists to process rst comments.  The Linux kernel
> uses a custom javadoc-like syntax (for historical reasons) for man
> pages.  Manually converting our comments is a non-starter so there's no
> getting around writing a Sowing parser in order to use Sphinx.  With
> such a parser written, we could make it "run once" to replace all the
> comments with a new format or (my plan) we could just keep our
> Sowing-style comments.

NumPy/SciPy use numpydoc, a Sphinx extension for their internal standard

  https://github.com/numpy/numpydoc/

I think the reference manual is pretty close to what we'd like for PETSc
man pages.  Note that each public interface has a dedicated page,
similar to PETSc.  An example page that could be analogous to our
KSP/Mat/Vec pages.

  https://docs.scipy.org/doc/scipy/reference/linalg.html

SciPy generated docs are 2977 HTML files totaling 46 MB.  PETSc is 5410
HTML files totaling 15 MB.  I think the difference in total size is a
combination of more cross-references and often more detailed
documentation (including inline examples).

SciPy docs took about 10 minutes to build, which is faster than PETSc's
current system, but still kind of slow and there is apparently no fast
incremental build.  There is a parallel option, but it didn't make much
difference (~5 minutes to say "100%", but almost 9 minutes to actually
complete).

Does anyone have experience with Sphinx performance for large projects?