Skip to content

Add Sphinx docs and port Developers Manual

Patrick Sanan requested to merge psanan/docs-sphinx-dev-manual into master

This MR adds machinery to build Sphinx documentation, as discussed in many venues over the last few years.

The Sphinx documentation corresponding to this branch can be viewed at https://docs.petsc.org/en/psanan-docs-sphinx-dev-manual/

In addition to boilerplate, we

  • Make a few changes to the existing docs and files, to allow smoother processing
  • Add a custom Sphinx extension which defines a new HTML translator, which we use to insert man page links in inline and block code listings
  • Port the developers manual
  • Add enough logic to build on ReadTheDocs, including configuring a minimal version of PETSc to get the manpage htmlmap file.
  • Add some (very) short guidelines on adding more Sphinx docs

You should be able to build locally as described in src/docs/sphinx_docs/README.md.

This is intended to provide a basis to port and improve more of the docs, starting with the users manual. The main selling points are

  1. It's on the web as HTML
  2. It's easier to contribute to

As such, comments on this general approach, as well as on the port of the dev manual, would be valuable at this stage!

Notes:

  • This doesn't (yet) incorporate the Sphinx docs into the main doc build (make alldoc)
Edited by Patrick Sanan

Merge request reports