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 oftable
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.