xCAT/xcat-core
2
0
Fork 0
mirror of https://github.com/xcat2/xcat-core.git synced 2025-05-22 03:32:04 +00:00
Code Issues Releases Wiki Activity

Add example to show how to edit doc:

Browse Source 
Section format
List format
Link/Reference
Footnotes
Comments
Table
Literal block/word
This commit is contained in:
wangxiaopeng 2015-09-02 01:26:33 -04:00
parent 38f7c13f88
commit 8a5c522292
2 changed files with 184 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/source/developers/.doc_guidelines.rst.swp Normal file
View File

Binary file not shown.

197
docs/source/developers/doc_guidelines.rst
View File

@ -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 </overview/support_list.html>`_.
Link to page ``http://server/overview/suport_list.html`` with **absolute file path** :doc:`support list </overview/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 </overview/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 <http://www.goole.com>`_.
Link to an external web page: `google <http://www.goole.com>`_: ::
Link to an external web page: `google <http://www.goole.com>`_
..
``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