3. Documentation Guidelines

See doc/README.md [https://github.com/ClusterLabs/pacemaker/blob/main/doc/README.md] in the source code repository for the kinds of documentation that Pacemaker provides.

3.1. Books

The doc/sphinx subdirectory has a subdirectory for each book by title. Each book’s directory contains .rst files, which are the chapter sources in reStructuredText [https://www.sphinx-doc.org/en/master/usage/restructuredtext/] format (with index.rst as the starting point).

Once you have edited the sources as desired, run make in the doc or doc/sphinx directory to generate all the books locally. You can view the results by pointing your web browser to (replacing PATH_TO_CHECKOUT and BOOK_TITLE appropriately):

file:///PATH_TO_CHECKOUT/doc/sphinx/BOOK_TITLE/_build/html/index.html

See the comments at the top of doc/sphinx/Makefile.am for options you can use.

Recommended practices:

• Use list-table instead of table for tables

• When documenting newly added features and syntax, add “*(since X.Y.Z)*” with the version introducing them. These comments can be removed when rolling upgrades from that version are no longer supported.