mirror of
https://github.com/xcat2/xcat-core.git
synced 2025-10-30 19:02:27 +00:00
Add example to show how to edit doc:
Section format List format Link/Reference Footnotes Comments Table Literal block/word
This commit is contained in:
wangxiaopeng
BIN
docs/source/developers/.doc_guidelines.rst.swp
Normal file
BIN
docs/source/developers/.doc_guidelines.rst.swp
Normal file
Binary file not shown.
@@ -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
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user