3. Documentation Guidelines

See 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 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):

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.