[petsc-dev] Users manual update

[Jed Brown]

Barry Smith <bsmith at petsc.dev> writes:

>   Aren't we likely to keep using sowing to generate the manual pages and then our own scripts to clean them up and add the links for source code HTML etc? But use Sphinx for the users manual and all web pages we maintain ourselves, FAQ etc? 
>
>   So we will always have two "build" parts for documentation and need to coordinate them?
>
>   Or do you have a plan to generate the manual pages with some other tool?  I don't think that is possible. BTW: I am updating the generation/processing of the manual pages in barry/2020-07-07/docs-no-makefiles  It should be much faster once several rounds of refactorization are done and will not require all the SOURCEC EXAMPLESC stuff in the makefiles anymore.

I would love for man pages to be able to reference Sphinx targets.  I believe they can only do this now by including a full URL, so the petsc-master path would link to petsc-maint or vice-versa, and the URLs are unchecked (or expensive to check).

AFAIK, one cannot currently use math in the man pages (as in /*F blocks of examples, [1]).  Perhaps we could get Sowing to do that.

As lower priority, it'd be nice to style the man pages consistently with the Sphinx docs.  This may be possible with a bit of CSS, or by making Sowing produce an intermediate representation for Sphinx to pick up.


[1] https://www.mcs.anl.gov/petsc/petsc-current/src/ts/tutorials/ex11.c.html
    Satish, this version is broken: https://www.mcs.anl.gov/petsc/petsc-master/src/ts/tutorials/ex11.c.html