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

Update doc Guidelines base on comments

Browse Source
This commit is contained in:
wangxiaopeng 2015-09-01 12:22:53 -04:00
parent 71318e9b69
commit 38f7c13f88
2 changed files with 19 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
docs/source/developers/edit_tips.rst → docs/source/developers/doc_guidelines.rst
View File

@ -1,13 +1,14 @@
The Tips to Edit this Document
==============================
Guidelines for xCAT Documentation
=================================
The following guidelines should be followed when making changes to the xCAT documentation to help create consistency in the documentation.
Add Links
---------
Hyperlinks -> Internal Links -> External Links
----------------------------------------------
Add links to refer other web page is a very common way in writting document, it's very helpful to reduce the doc duplication and make doc to be easy to understand. Following are several ways to add a link in the xCAT documentation.
* Add an Internal Link to ``Customized Link Target``
* **Add an Internal Link to ``Customized Link Target``**
``Customized Link Target`` means a user defined **Link Target**.
@ -27,13 +28,13 @@ Define a **Link Target** named ``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
* **Add an Internal Link to Current Page**
Link to an internal section in current page: `The Tips to Edit this Document`_.
``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
* **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>`_.
@ -41,7 +42,7 @@ Define a **Link Target** named ``my_link_target``:
``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
* **Add an External Link**
Link to an external web page: `google <http://www.goole.com>`_.
@ -49,18 +50,22 @@ Define a **Link Target** named ``my_link_target``:
``Note:`` The ``https://`` keyword must be added before the web page URL.
* Add a Link with explicit URL displayed
* **Add a Link with Explicit URL Displayed**
Link to http://www.google.com
``Usage:`` Make a link and display the URL.
Add OS or ARCH Specific Branches
-----------------------------------------------
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, please use the following format to add specific branches.
* **[RH7]**
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.

2
docs/source/developers/index.rst
View File

@ -9,7 +9,7 @@ This page is for developers interested in working with xCAT.
license/index.rst
github/index.rst
edit_tips.rst
doc_guidelines.rst
developer_guide.rst
programming_tips.rst
debug_xcat.rst