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
'''''''''''''''
Bullet one
The Content.
Bullet Two
The Content.
* Bullet one
The Content.
* Bullet Two
The Content.
- Item 1
- item a
- item b
- Item 2
- item a
1. Item 1
a) item a
b) item b
2. Item 2
a) item a
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 .. toctree::
.
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 links to refer other web page is a very common way in writing document, it's very helpful to reduce the doc duplication and make docs easy to understand. Following are several ways to add a link in the xCAT documentation.
- Add an Internal Link to ``Customized Link Target``
Customized Link Target
means a user defined Link Target.
Define a Link Target named
my_link_target
: :.. _my_link_target: **Customized Link Target** This part of content is a link target which can be linked by other content.
Add an Internal Link to Current Page
Link to an internal section in current page: Guidelines for xCAT Documentation: :
`Guidelines for xCAT Documentation`_
Add an Internal Link to Other Page via File Path
Link to page http://server/overview/suport_list.html with absolute file path :
:doc:`support list </overview/support_list>`
Add an External Link
Link to an external web page: google: :
`google <http://www.goole.com>`_
Add a Link with Explicit URL Displayed
Link to http://www.google.com: :
http://www.google.com
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.
[RHEL7]
This part of description is for [rh7] specific.
[SLES]
This part of description is for [sles] specific.
[PPC64LE]
This part of description is for [ppc64le] specific.
* **[RHEL7]**
This part of description is for [rh7] specific.
The sentence started with ..
will be a comment that won't be displayed in the doc. :
.. This is a comment
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 Literal Word
: :
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 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 | - Cells | +------------+ span rows. | - contain | | body row 4 | | - blocks. | +------------+------------+-----------+
+------------+------------+-----------+
| 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. |
+------------+------------+-----------+
This is the first example of footnotes1.
This is the second example of footnotes2.
This is the first example of footnotes [1]_.
This is the second example of footnotes [2]_.
.. [1] First footnote
.. [2] Second footnote