From f3b8e39827ebe3868e80725d582685a9230a6352 Mon Sep 17 00:00:00 2001 From: Mark Gurevich Date: Tue, 31 May 2016 11:38:02 -0400 Subject: [PATCH 1/2] Add some xCAT documentation writing guidelines --- .../developers/guides/docs/doc_guidelines.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/source/developers/guides/docs/doc_guidelines.rst b/docs/source/developers/guides/docs/doc_guidelines.rst index 347ece7cd..c42f5abb5 100644 --- a/docs/source/developers/guides/docs/doc_guidelines.rst +++ b/docs/source/developers/guides/docs/doc_guidelines.rst @@ -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 ---------------------------------------------- From 8ea1c26113c9ccf51ec0575b629ed14979897204 Mon Sep 17 00:00:00 2001 From: Mark Gurevich Date: Wed, 1 Jun 2016 09:56:32 -0400 Subject: [PATCH 2/2] Fix doc_guidelines.rst based on pull request review --- docs/source/developers/guides/docs/doc_guidelines.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/developers/guides/docs/doc_guidelines.rst b/docs/source/developers/guides/docs/doc_guidelines.rst index c42f5abb5..3fe458d0c 100644 --- a/docs/source/developers/guides/docs/doc_guidelines.rst +++ b/docs/source/developers/guides/docs/doc_guidelines.rst @@ -70,15 +70,15 @@ To add contents of a document file inside another file, use ``.. include::``. Th .. 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. +``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. +``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 ----------------------------------------------