[petsc-dev] Manual page improvements! (Docs MRs to main until PETSc 3.18 is released)

[Patrick Sanan]

We just merged a large change to the documentation into the main branch.
This integrates the manual pages into the documentation build with Sphinx,
so you can do things like

- Find manual page content with the website search box
- Add images, inline code, equations, citations, links to the users manual,
etc. on the man pages

Check it out at petsc.org/main/docs/manualpages . For an example of a
manual page updated to take advantage of the new features, search for
"PCFIELDSPLIT".

This is accomplished by allowing inline MyST (Markdown) syntax [1] in the
usual man page blocks in the source code. More details at the MR [2].

Unlike most previous docs changes, this has only been done on the main
branch. So, **until PETSc 3.18 is released, make documentation MRs to main**,
unless fixing something particularly critical on the release branch, or
making a change which you've tested won't cause (serious) merge conflicts
when release is merged into main.

I'm hoping that developers will try using the man pages at petsc.org/main
and thus be able to give feedback. There are a number of known issues, and
hopefully the most egregious of these can be resolved before the release.
You can find links to these issues in the MR description [2] or on the list
of "docs"-labelled issues on GitLab [3]. If so inclined,

- use the thumbs-up and thumbs-down buttons on the issues to help
prioritize
- comment about formatting on issue #1156 [4]
- suggest candidates for specific man pages to make prettier at  #1155 [5]
- add comments on other topics to existing issues or open new ones (with
the "docs" label)
- assign yourself to any issues you'd like to be involved in resolving

[1]: https://myst-parser.readthedocs.io/en/latest/index.html
[2]: https://gitlab.com/petsc/petsc/-/merge_requests/4989
[3]:
https://gitlab.com/petsc/petsc/-/issues/?sort=updated_desc&state=opened&label_name%5B%5D=docs
[4]: https://gitlab.com/petsc/petsc/-/issues/1156
[5]: https://gitlab.com/petsc/petsc/-/issues/1155
[6]: https://petsc.org/main/docs/manualpages/PC/PCFIELDSPLIT
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20220504/82de5772/attachment.html>