From 8a5c5222922d99396cbee4fc333088d7ceb2faab Mon Sep 17 00:00:00 2001 From: wangxiaopeng Date: Wed, 2 Sep 2015 01:26:33 -0400 Subject: [PATCH] Add example to show how to edit doc: Section format List format Link/Reference Footnotes Comments Table Literal block/word --- .../source/developers/.doc_guidelines.rst.swp | Bin 0 -> 20480 bytes docs/source/developers/doc_guidelines.rst | 197 ++++++++++++++++-- 2 files changed, 184 insertions(+), 13 deletions(-) create mode 100644 docs/source/developers/.doc_guidelines.rst.swp diff --git a/docs/source/developers/.doc_guidelines.rst.swp b/docs/source/developers/.doc_guidelines.rst.swp new file mode 100644 index 0000000000000000000000000000000000000000..2fa27799e429e2c479adf0a6ee1bdf2966b68d88 GIT binary patch literal 20480 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 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 +