diff --git a/docs/source/developers/.doc_guidelines.rst.swp b/docs/source/developers/.doc_guidelines.rst.swp new file mode 100644 index 000000000..2fa27799e Binary files /dev/null and b/docs/source/developers/.doc_guidelines.rst.swp differ diff --git a/docs/source/developers/doc_guidelines.rst b/docs/source/developers/doc_guidelines.rst index 2ee4b0801..c3562a575 100644 --- a/docs/source/developers/doc_guidelines.rst +++ b/docs/source/developers/doc_guidelines.rst @@ -2,6 +2,62 @@ Guidelines for xCAT Documentation ================================= The following guidelines should be followed when making changes to the xCAT documentation to help create consistency in the documentation. +Document Structure +------------------ + +Section Structure +````````````````` + +xCAT doc page may have 4 levels of title at most: :: + + The First Title + =============== + + The Second Title + ---------------- + + The Third Title + ``````````````` + + The Forth Title + ''''''''''''''' + +List Structure +`````````````` + +Bullet Lists +'''''''''''' + +* Bullet one + + The Content. +* Bullet Two + + The Content. + +:: + + * Bullet one + The Content. + * Bullet Two + The Content. + +Enumerated List +''''''''''''''' + +1. Item 1 + a) item a + b) item b +2. Item 2 + a) item a + +:: + + 1. Item 1 + a) item a + b) item b + 2. Item 2 + a) item a Hyperlinks -> Internal Links -> External Links ---------------------------------------------- @@ -12,39 +68,59 @@ Add links to refer other web page is a very common way in writting document, it ``Customized Link Target`` means a user defined **Link Target**. -Define a **Link Target** named ``my_link_target``: - -------------------- - .. _my_link_target: - **Customized Link Target** + Define a **Link Target** named ``my_link_target``: :: - This part of content is a link target which can be linked by other content. + .. _my_link_target: -------------------- + **Customized Link Target** - Link to the customized link target ``my_link_target``: my_link_target_. + This part of content is a link target which can be linked by other content. + +.. + + Link to the customized link target ``my_link_target``: `my_link_target`_: :: + + Link to the customized link target ``my_link_target``: my_link_target_. + +.. ``Usage:`` This method is used to add a **Link Target** in any page that can be referred by any other pages. * **Add an Internal Link to Current Page** - Link to an internal section in current page: `The Tips to Edit this Document`_. + Link to an internal section in current page: `Guidelines for xCAT Documentation`_: :: + + Link to an internal section in current page: `Guidelines for xCAT Documentation`_ + +.. ``Usage:`` Every title of a section is an auto-generated 'link target', so you can use it directly. But it's only available inside the current page. * **Add an Internal Link to Other Page via File Path** - Link to page ``http://server/overview/suport_list.html`` with absolute file path `support list `_. + Link to page ``http://server/overview/suport_list.html`` with **absolute file path** :doc:`support list `: :: - Link to page ``http://server/overview/suport_list.html`` with relative file path `support list <../overview/support_list.html>`_. + Link to page ``http://server/overview/suport_list.html`` with **absolute file path** :doc:`support list ` + +.. + + Link to page ``http://server/overview/suport_list.html`` with **relative file path** :doc:`support list <../overview/support_list>`: :: + + Link to page ``http://server/overview/suport_list.html`` with **relative file path** :doc:`support list <../overview/support_list>` + +.. ``Usage:`` When you want to link to another whole page but don't want to make a ``Customized Link Target`` in that source page, you can use the file path to link it directly. * **Add an External Link** - Link to an external web page: `google `_. + Link to an external web page: `google `_: :: + + Link to an external web page: `google `_ + +.. ``Usage:`` When you want to link to a page which does not belong to xCAT documentation. @@ -52,10 +128,15 @@ Define a **Link Target** named ``my_link_target``: * **Add a Link with Explicit URL Displayed** - Link to http://www.google.com + Link to http://www.google.com: :: + + Link to http://www.google.com + +.. ``Usage:`` Make a link and display the URL. + Add OS or ARCH Specific Contents -------------------------------- @@ -77,5 +158,95 @@ The valid keyword includes: **RHEL**, **SLES**, **UBUNTU**, **CENTOS**, **X86_64 This part of description is for [ppc64le] specific. +:: + + * **[RHEL7]** + + This part of description is for [rh7] specific. + + +Miscellaneous +------------- + +Add a Comment +````````````` + +.. Try the 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 + +Decorate Word +````````````` + +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 +``````````` + +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. | + +------------+------------+-----------+ + +Add Footnotes +````````````` + +This is the first example of footnotes [1]_. + +This is the second example of footnotes [2]_. + +:: + + This is the first example of footnotes [1]_. + This is the second example of footnotes [2]_. + + .. [1] First footnote + .. [2] Second footnote + +------------------------ + +.. [1] First footnote +.. [2] Second footnote +