Guidelines for xCAT Documentation¶
The following guidelines should be followed when making changes to the xCAT documentation to help create consistency in the documentation.
xCAT doc page may have 4 levels of title at most:
The First Title =============== The Second Title ---------------- The Third Title ``````````````` The Forth Title '''''''''''''''
Include another file¶
To add contents of a document file inside another file, use
.. include::. This is useful when a common information needs to be displayed in multiple files, without the use of a hyperlink.
.. include:: config_common.rst
Note: Do not put customized link targets, such as
.. _my_link_taget: inside the file to be included. If you do, a warning for a duplicate label will be displayed during the documentation build process.
Index.rst files contain the
.. toctree:: tag. Files listed under that tag will have links to them displayed in the left side navigation area. If a documentation file does not wish to be accessible from the navigation area, do not list it under the
Note: If a file is not listed under the
.. toctree:: it might generate a warning during the documentation build
WARNING: document isn't included in any toctree. To eliminate such warning, add the file to the
exclude_patterns list in the
docs/source/conf.py file. However, do not add a file to the
exclude_patterns list if it contains a customized link target, such as
.. _my_link_taget:. This link target will not be visible to other files and a
WARNING: undefined label: will be displayed during the documentation build.
Add OS or ARCH Specific Contents¶
When writing a common xCAT doc, we always encounter the case that certain small part of content needs to be OS or ARCH specific. In this case, use the following format to add specific branches.
The keyword in the  can be an OS name or ARCH name, or any name which can distinguish the content from other part.
The valid keyword includes: RHEL, SLES, UBUNTU, CENTOS, X86_64, PPC64, PPC64LE. If the keyword is an OS, it can be postfixed with an OS version e.g. RHEL7.
This part of description is for [rh7] specific.
This part of description is for [sles] specific.
This part of description is for [ppc64le] specific.
* **[RHEL7]** This part of description is for [rh7] specific.
Add a Comment¶
The sentence started with
.. will be a comment that won’t be displayed in the doc.
.. This is a comment
Add Literal Block¶
If you want to add a paragraph of code or something that don’t want to be interpreted by browser:
If you want to add a paragraph of code or something that don't want to be interpreted by browser: :: #lsdef node1 #tabdump
If you want to display one or several words to be
If you want to display one or several words to be ``Literal Word``
If you want to make a strong emphasis of the word:
If you want to make a **strong emphasis** of the word:
Add a Table¶
Add a table in the doc:
|Header 1||Header 2||Header 3|
|body row 1||column 2||column 3|
|body row 2||Cells may span columns.|
|body row 3||Cells may span rows.||
|body row 4|
+------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | body row 1 | column 2 | column 3 | +------------+------------+-----------+ | body row 2 | Cells may span columns.| +------------+------------+-----------+ | body row 3 | Cells may | - Cells | +------------+ span rows. | - contain | | body row 4 | | - blocks. | +------------+------------+-----------+