xCAT/xcat-core
2
0
Fork 0
mirror of https://github.com/xcat2/xcat-core.git synced 2025-10-31 11:22:27 +00:00
Code Issues Releases Wiki Activity

Add some xCAT documentation writing guidelines

Browse Source
This commit is contained in:
Mark Gurevich
2016-05-31 11:38:02 -04:00
parent 1578038632
commit f3b8e39827
1 changed files with 18 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/source/developers/guides/docs/doc_guidelines.rst
View File

@@ -62,6 +62,24 @@ Enumerated List
2. Item 2
a) item a
Include another file
--------------------
To add contents of a document file inside another file, use ``.. include::``. This is usefull when a common information needs to be displayed in multiple files, whithout the use of a hyperlink.
::
.. include:: config_common.rst
..
``Note:`` Do not put customized link targets, such as ``.. _my_link_taget:`` inside the file to be included. If you do, a warning for a duplicate label will be displayed during the documentation build process.
Index file
--------------------
Index.rst files contain the ``.. toctree::`` tag. Files listed under that tag will have links to them displayed in the left side navigation area. If a documentation file does not wish to be accessbile from the navigation area, do not list it under the ``.. toctree::``.
``Note:`` If a file is not listed under the ``.. toctree::`` it might generate a warning during the documentation build ``WARNING: document isn't included in any toctree``. To eliminate such warning, add the file to the ``exclude_patterns`` list in the ``docs/source/conf.py`` file. However, do not add a file to the ``exclude_patterns`` list if it contains a customized link target, such as ``.. _my_link_taget:``. This link target will not be visible to other files and a ``WARNING: undefined label:`` will be displayed during the documentation build.
Hyperlinks -> Internal Links -> External Links
----------------------------------------------