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
