=============================================
-OPNFV User guide documentation instruction
+Including your Documentation
=============================================
-Including your Documentation
-------------------------------
+.. contents::
+ :depth: 3
+ :local:
+
+In your project repository
+----------------------------
-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:
+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 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
+In OPNFVDocs Composite Documentation
+--------------------------------------
-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.
+In toctree
++++++++++++
-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.
+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
+
+ 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:
+
+
+.. code-block:: bash
+
+ .. 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::
+
+ This is a reference to :ref:`a-label`
+
+or::
+
+ This is a reference to :ref:`a section I really liked <a-label>`
+
+.. 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.
+
+.. code-block:: bash
+
+ 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.
+
+Testing: Build Documentation Locally
+---------------------------------------
+
+Composite OPNFVDOCS documentation
++++++++++++++++++++++++++++++++++++
+To build whole documentation under opnfvdocs/, follow these steps:
+
+Install virtual environment.
+
+.. code-block:: bash
+
+ sudo pip install virtualenv
+ cd /local/repo/path/to/project
+
+Download the OPNFVDOCS repository.
+
+.. code-block:: bash
+
+ git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
+
+Change directory to opnfvdocs & install requirements.
+
+.. code-block:: bash
+
cd opnfvdocs
- git review -s
- vim docs/userguide/feature-usage.rst '
+ sudo pip install -r etc/requirements.txt
+Update submodules, build documentation using tox & then open using any browser.
-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
+
+ cd opnfvdocs
+ git submodule update --init
+ tox -edocs
+ firefox docs/_build/html/index.html
+
+.. note:: Make sure to run `tox -edocs` and not just `tox`.
+
+Individual project documentation
++++++++++++++++++++++++++++++++++++
+To test how the documentation renders in HTML, follow these steps:
+
+Install virtual environment.
+
+.. code-block:: bash
+
+ sudo pip install virtualenv
+ cd /local/repo/path/to/project
+
+Download the opnfvdocs repository.
.. 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''
+ git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
-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 '
+Change directory to opnfvdocs & install requirements.
+.. code-block:: bash
-Once you have the file open, add your projects repository to the get_repo_names() function:
+ cd opnfvdocs
+ sudo pip install -r etc/requirements.txt
-.. 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>"
+Move the conf.py file to your project folder where RST files have been kept:
+
+.. code-block:: bash
+
+ mv opnfvdocs/docs/conf.py <path-to-your-folder>/
+
+Move the static files to your project folder:
+
+.. code-block:: bash
+ mv opnfvdocs/_static/ <path-to-your-folder>/
-Once you have made these changes you need to push the patch back to the opnfvdocs team for review and integration.
+Build the documentation from within your project folder:
.. code-block:: bash
- ' git add . '
- ' git commit --signoff --all '
- ' git review '
-
+ sphinx-build -b html <path-to-your-folder> <path-to-output-folder>
-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.
+Your documentation shall be built as HTML inside the
+specified output folder directory.
Code Review / opnfvdocs.git / blobdiff