README.md
1# Pacemaker Documentation
2
3Pacemaker has multiple forms of documentation:
4
5* The primary end-user documentation is a series of "books":
6
7 * Clusters From Scratch: Simplified walk-through of setting up a
8 cluster for the first time
9 * Pacemaker Administration: Tips for managing a cluster
10 * Pacemaker Development: How to work on the Pacemaker code base
11 * Pacemaker Explained: Configuration reference guide
12 * Pacemaker Remote: Configuration and walk-throughs for extended
13 clusters
14
15 The source for these is kept in this directory's sphinx subdirectory.
16 Generated versions are available online in epub, PDF, and HTML format at:
17
18 https://clusterlabs.org/pacemaker/doc/
19
20* Annotated source code in HTML format can be generated by running
21 "make global" in this directory, which requires the gtags and htags tools.
22 This is generated for releases and can be viewed online at:
23
24 https://clusterlabs.org/pacemaker/global/
25
26* Pacemaker manual pages are generated and installed automatically when
27 building the software. HTML versions can be generated by running
28 "make manhtml" in this directory, which requires the groff tool.
29 This is generated for releases and can be viewed online at:
30
31 https://clusterlabs.org/pacemaker/man/
32
33* For developers, documentation for Pacemaker's public C API is generated
34 by running "make doxygen" in this directory, which requires the doxygen tool.
35 This is generated for releases and can be viewed online at:
36
37 https://clusterlabs.org/pacemaker/doxygen/
38
39* Also for developers, a report of Pacemaker ABI compatibility between any two
40 commits can be generated by running in this directory:
41
42 make LAST_RELEASE=$EARLIER_COMMIT TAG=$NEWER_COMMIT abi-www
43
44 which requires the abi-compliance-checker tool. This is generated for each
45 release compared to the previous release and can be viewed online at:
46
47 https://clusterlabs.org/pacemaker/abi/
48
49* In addition, there are a few old text files in this directory focusing on
50 particular characteristics of Pacemaker clusters. These are mostly outdated
51 but do still have some useful information. The plan is to incorporate an
52 updated version of them into the books.
53
54## Editing the Books
55
56The sphinx subdirectory has a subdirectory for each book by title. Each book's
57directory contains .rst files, which are the chapter sources in
58reStructuredText format (with index.rst as the starting point).
59
60Once you have edited the sources as desired, run "make" here or in the sphinx
61subdirectory to generate all the books locally. You can view the results by
62pointing your web browser to (replacing PATH\_TO\_CHECKOUT and BOOK\_TITLE
63appropriately):
64
65 file:///PATH_TO_CHECKOUT/doc/sphinx/BOOK_TITLE/_build/html/index.html
66
67See the comments at the top of doc/sphinx/Makefile.am for various options you
68can use. For a guide to sphinx-flavored reStructuredText, see:
69
70 https://www.sphinx-doc.org/en/master/usage/restructuredtext/
71