Barry Smith <[email protected]> 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
