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

[Patrick Sanan]

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

For instance, can we start by just generating stub .rst-formatted man
pages, which include a link to the existing man pages?

Am So., 16. Juni 2019 um 20:25 Uhr schrieb Jed Brown <jed at jedbrown.org>:

> 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?
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20190617/2aaf47f6/attachment.html>