Merge "New docs for 'How to include documentation'"

1 files changed, 98 insertions, 37 deletions

diff --git a/docs/how-to-use-docs/include-documentation.rst b/docs/how-to-use-docs/include-documentation.rst
index 8ad1a2753..f1f299e63 100644
--- a/docs/how-to-use-docs/include-documentation.rst
+++ b/docs/how-to-use-docs/include-documentation.rst
@@ -1,66 +1,127 @@
 
 =============================================
-OPNFV User guide documentation instruction
+Including your Documentation
 =============================================
 
-Including your Documentation
-------------------------------
+.. contents::
+   :depth: 3
+   :local:
 
-Add your documentation to your repository in the folder structure and according to the template listed above. The documentation template you will require are available in the opnfvdocs repository, you should copy the relevant templates to the /docs/userguide directory in your repository. For instance if I wanted to document enabling my feature set in the platform I would follow an example like:
+In your project repository
+----------------------------
+
+Add your documentation to your repository in the folder structure and
+according to the templates listed above. The documentation templates you
+will require are available in opnfvdocs/docs/templates/ repository, you should
+copy the relevant templates to your <repo>/docs/ directory in your repository.
+For instance if you want to document userguide, then your steps shall be
+as follows:
 
 .. code-block:: bash
-   mkdir <my_repo>/docs/userguide
+
    git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git
-   cp opnfvdocs/docs/userguide/userguide.rst <my_repo>/docs/userguide
+   cp -p opnfvdocs/docs/userguide/* <my_repo>/docs/userguide/
 
 
-You should then add the relevant information to the template that will explain the usage of your feature and instructions for validating that the feature was used successfully like checking the results of specific test cases. Be sure to maintain the creative commons license from the template and ensure all your documentation files include the license information.
+You should then add the relevant information to the template that will
+explain the documentation. When you are done writing, you can commit
+the documentation to the project repository.
+
+.. code-block:: bash
+
+   git add .
+   git commit --signoff --all
+   git review
 
-Once your documentation is ready you should ensure they are compiled into the staging files by adding them to the master <section>.rst file in the opnfvdocs repository. The staging files are structured in such a way that you should refer to your document in the correct section of the document structure.
+In OPNFVDocs Composite Documentation
+--------------------------------------
+
+In toctree
++++++++++++
+
+To import project documents from project repositories, we use submodules.
+ Each project is stored in :code:`opnfvdocs/docs/submodule/` as follows:
+
+.. image:: Submodules.jpg
+   :scale: 50 %
+
+To include your project specific documentation in the composite documentation,
+first identify where your project documentation should be included.
+Say your project userguide should figure in the ‘OPNFV Userguide’, then:
 
-An example of how to add your documentation to the relevant sections of the feature-usage.rst file might be:
 
 .. code-block:: bash
-   git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git
-   cd opnfvdocs
-   git review -s
-   vim docs/userguide/feature-usage.rst '
 
+   vim opnfvdocs/docs/release/userguide.introduction.rst
+
+This opens the text editor. Identify where you want to add the userguide.
+If the userguide is to be added to the toctree, simply include the path to
+it, example:
 
-At this point you should add the references to your files into the index.rst file, for instance in the feature description section you would add the line:
-The following sections of the user guide provide feature specific usage guidelines and references.
-Providing users the necessary information to leveraging the features in the platform,
-some operation in this section may refer back to the guides in the general system usage section.
 
 .. code-block:: bash
-.. include:: ../projects/promise/userguide/userguide.rst
-.. include:: ../projects/copper/userguide/userguide.rst  Using Brahmaputra Features
-.. include:: ../projects/<my_repo>/userguide/userguide.rst''
 
+   .. toctree::
+       :maxdepth: 1
+
+    submodules/functest/docs/userguide/index
+    submodules/bottlenecks/docs/userguide/index
+    submodules/yardstick/docs/userguide/index
+    <submodules/path-to-your-file>
+
+As Hyperlink
++++++++++++++
+
+It's pretty common to want to reference another location in the
+OPNFV documentation and it's pretty easy to do with
+reStructuredText. This is a quick primer, more information is in the
+`Sphinx section on Cross-referencing arbitrary locations
+<http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
+
+Within a single document, you can reference another section simply by::
+
+   This is a reference to `The title of a section`_
+
+Assuming that somewhere else in the same file there a is a section
+title something like::
+
+   The title of a section
+   ^^^^^^^^^^^^^^^^^^^^^^
+
+It's typically better to use ``:ref:`` syntax and labels to provide
+links as they work across files and are resilient to sections being
+renamed. First, you need to create a label something like::
+
+   .. _a-label:
+
+   The title of a section
+   ^^^^^^^^^^^^^^^^^^^^^^
+
+.. note:: The underscore (_) before the label is required.
+
+Then you can reference the section anywhere by simply doing::
 
-If this is the first contribution from your project to the composite document files you will need to add your project to the build-composite.sh file in the opnfvdocs directory. This is done my editing the jsdgf file and adding your repository name to the get_repo_names() function of the script. Assuming you are still in the opnfvdocs directory edit the file with the following command:
-' vim build-composite.sh '
+    This is a reference to :ref:`a-label`
 
+or::
 
-Once you have the file open, add your projects repository to the get_repo_names() function:
+    This is a reference to :ref:`a section I really liked <a-label>`
 
-.. code-block:: python
-	get_repo_names() {
-	  # NOTE: Not all repositories are ready for the composite docs,
-	  #       so we have the repo name list here to add project docs
-	  #       one by one. This will be replaced by the list in project.cfg .
-	  # grep -v '^#' releng/jjb/opnfvdocs/project.cfg | sort
-	  echo "sdnvpn"
-	  echo "<my_repo>"
+.. note:: When using ``:ref:``-style links, you don't need a trailing
+          underscore (_).
 
+Because the labels have to be unique, it usually makes sense to prefix
+the labels with the project name to help share the label space, e.g.,
+``sfc-user-guide`` instead of just ``user-guide``.
 
-Once you have made these changes you need to push the patch back to the opnfvdocs team for review and integration.
+Once you have made these changes you need to push the patch back to
+the opnfvdocs team for review and integration.
 
 .. code-block:: bash
-	' git add . '
-	' git commit --signoff --all '
-	' git review '
 
- 
+   git add .
+   git commit --signoff --all
+   git review
 
-Be sure to add the project leader of the opnfvdocs project as a reviewer of the change you just pushed in gerrit. Also be aware that once the text is available in the context of the broader release document it may require some revising and editorial work to prepare it for release.
+Be sure to add the project leader of the opnfvdocs project
+as a reviewer of the change you just pushed in gerrit.