diff --git a/doc/README.md b/doc/README.md index c406fadcba..07f546efbb 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,70 +1,56 @@ # Pacemaker Documentation Pacemaker has multiple forms of documentation: * The primary end-user documentation is a series of "books": - * Clusters From Scratch: Simplified walk-through of setting up a - cluster for the first time - * Pacemaker Administration: Tips for managing a cluster - * Pacemaker Development: How to work on the Pacemaker code base - * Pacemaker Explained: Configuration reference guide - * Pacemaker Remote: Configuration and walk-throughs for extended - clusters + * *Clusters From Scratch*: Simplified walk-through of setting up a cluster + for the first time + * *Pacemaker Administration*: Tips for managing a cluster + * *Pacemaker Development*: How to work on the Pacemaker code base + * *Pacemaker Explained*: Configuration reference guide + * *Pacemaker Remote*: Configuration and walk-throughs for extended clusters The source for these is kept in this directory's sphinx subdirectory. Generated versions are available online in epub, PDF, and HTML format at: https://clusterlabs.org/pacemaker/doc/ * Annotated source code in HTML format can be generated by running "make global" in this directory, which requires the gtags and htags tools. This is generated for releases and can be viewed online at: https://clusterlabs.org/pacemaker/global/ * Pacemaker manual pages are generated and installed automatically when building the software. HTML versions can be generated by running "make manhtml" in this directory, which requires the groff tool. This is generated for releases and can be viewed online at: https://clusterlabs.org/pacemaker/man/ * For developers, documentation for Pacemaker's public C API is generated by running "make doxygen" in this directory, which requires the doxygen tool. This is generated for releases and can be viewed online at: https://clusterlabs.org/pacemaker/doxygen/ * Also for developers, a report of Pacemaker ABI compatibility between any two commits can be generated by running in this directory: make LAST_RELEASE=$EARLIER_COMMIT TAG=$NEWER_COMMIT abi-www which requires the abi-compliance-checker tool. This is generated for each release compared to the previous release and can be viewed online at: https://clusterlabs.org/pacemaker/abi/ * In addition, there are a few old text files in this directory focusing on particular characteristics of Pacemaker clusters. These are mostly outdated but do still have some useful information. The plan is to incorporate an updated version of them into the books. -## Editing the Books +## Editing the Documentation -The 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" here or in the sphinx -subdirectory 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 various options you -can use. For a guide to sphinx-flavored reStructuredText, see: - - https://www.sphinx-doc.org/en/master/usage/restructuredtext/ +If you wish to contribute documentation changes, please see the "Documentation" +chapter of *Pacemaker Development*. diff --git a/doc/sphinx/Pacemaker_Development/documentation.rst b/doc/sphinx/Pacemaker_Development/documentation.rst new file mode 100644 index 0000000000..6880bb04a3 --- /dev/null +++ b/doc/sphinx/Pacemaker_Development/documentation.rst @@ -0,0 +1,35 @@ +.. index:: + pair: documentation; guidelines + +Documentation Guidelines +------------------------ + +See `doc/README.md +`_ in the +source code repository for the kinds of documentation that Pacemaker provides. + +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): + + 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. diff --git a/doc/sphinx/Pacemaker_Development/index.rst b/doc/sphinx/Pacemaker_Development/index.rst index cbe149945e..1e80df9cfa 100644 --- a/doc/sphinx/Pacemaker_Development/index.rst +++ b/doc/sphinx/Pacemaker_Development/index.rst @@ -1,33 +1,34 @@ Pacemaker Development ===================== *Working with the Pacemaker Code Base* Abstract -------- This document has guidelines and tips for developers interested in editing Pacemaker source code and submitting changes for inclusion in the project. Start with the FAQ; the rest is optional detail. Table of Contents ----------------- .. toctree:: :maxdepth: 3 :numbered: faq general + documentation python c components helpers evolution Index ----- * :ref:`genindex` * :ref:`search`