[doc.git] / docs / guide / onap-developer / how-to-use-docs / include-documentation.rst

.. This work is licensed under a Creative Commons Attribution 4.0 International License.


Setting Up
==========
Some initial set up is required to connect a project with
the master document structure and enable automated publishing of
changes as summarized in the following diagram and description below 
below.

.. seqdiag::
   :height: 700
   :width: 1000

   seqdiag {
     RD [label = "Read The Docs",                color =lightgreen ];
     DA [label = "Doc Project\nAuthor/Committer",   color=lightblue];
     DR [label = "Doc Gerrit Repo" ,                     color=pink];
     PR [label = "Other Project\nGerrit Repo",          color=pink ];
     PA [label = "Other Project\nAuthor/Committer", color=lightblue];
     
     === One time setup doc project only ===
     RD  ->   DA [label = "Acquire Account" ]; 
     DA  ->   DR [label = "Create initial\n doc repository content"];
     DA  <<-- DR [label = "Merge" ];
     RD  <--  DA [label = "Connect gerrit.onap.org" ];
     === For each new project repository containing document source ===
     DA  ->   PR [label = "Create in new project repo\ntop level directory and index.rst" ];
     PR  <--  PA [label = "Review/Approve" ];
     DA  <--  PR [label = "Merge" ];     
     DA  ->   DR [label = "Add new project repo as\ngit submodule" ];
     DA  <--  DR [label = "Merge" ];
     }
     
     

Setup doc project
-----------------
These steps are performed only once for the doc project and include:

(1) creating in the doc repository an initial:
        - sphinx master document index
        - a directory structure aligned with the document structure
        - tests performed in jenkins verify jobs
        - sphinx configuration
  
(2) establishing an account at readthedocs connected with the doc
doc project repo in gerrit.onap.org.


Setup new project repositories(s)
---------------------------------
These steps are performed for each new project repo (referred to in the
next two code blocks as $reponame):

(1) clone, modify, and commit to the other project an initial: docs top
level directory; index.rst; any other intial content.   

.. code-block:: bash

   reponame=test
   git clone ssh://<your_id>@gerrit.onap.org:29418/$reponame
   cd $reponame
   mkdir docs
   echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License.

   TODO Add files to toctree and delete this header
   ------------------------------------------------
   .. toctree::
      :maxdepth: 1
      
   " >  docs/index.rst
   
   git add .
   git commit -m "Add RST docs directory and index" -s
   git commit --amend
   # modify the commit message to comply with ONAP best practices
   git review
   
When the above commit is reviewed and merged complete step 2 before any
new changes are merged into $reponame.
        
(2) clone, modify, and commit to the doc project: a directory under doc/docs/submodules with the same path/name as the other project and initialized as a git submodule.
        
.. code-block:: bash

   git clone ssh://<your_id>@gerrit.onap.org:29418/doc
   # For top level repositories use the following
   mkdir doc/docs/submodules/$reponame
   # For lower level repositories you may need to make a directory for each node in path
   
   echo "   $reponame <../submodules/$reponame/docs/index>" >> docs/release/repolist.rst
   
   git submodule git https://gerrit.onap.org/r/$reponame
   git submodule init $reponame/
   git submodule update $reponame/
   
   
   git add .
   git commit -m "Add $reponame as a submodule" -s
   git commit --amend
   # modify the commit message to comply with ONAP best practices
   git review
   


The diagram below illustrates what is accomplished in the setup steps
above from the perspective of a file structure created for a local test,
a jenkins verify job, and/or publish release documentation including:

  - all ONAP gerrit project repositories,
  - the doc project repository master document index.rst, templates, configuration
  - the submodules directory where other project repositories and directories/files may be referenced


.. graphviz::

   
   digraph docstructure {
   size="8,12";
   node [fontname = "helvetica"];
   // Align gerrit repos and docs directories
   {rank=same doc aaf aai reponame repoelipse vnfsdk vvp}
   {rank=same confpy release templates masterindex submodules otherdocdocumentelipse}


   //Illustrate Gerrit Repos and provide URL/Link for complete repo list
   gerrit [label="gerrit.onap.org/r", href="https://gerrit.onap.org/r/#/admin/projects/" ];
   gerrit -> doc;
   gerrit -> aaf;
   gerrit -> aai;
   gerrit -> reponame; 
   gerrit -> repoelipse;
             repoelipse [label=". . . ."];
   gerrit -> vnfsdk;
   gerrit -> vvp;

   //Show example of local reponame instance of component info
   reponame -> reponamedocsdir;
   reponamesm -> reponamedocsdir;  
                    reponamedocsdir [label="docs"];
   reponamedocsdir -> newrepodocsdirindex; 
                         newrepodocsdirindex [label="index.rst", shape=box];

   //Show detail structure of a portion of doc/docs 
   doc  -> docs;
   docs -> confpy;                   
           confpy [label="conf.py",shape=box];
   docs -> masterindex; 
           masterindex [label="Master index.rst", shape=box];
   docs -> release;
   docs -> templates;                                
   docs -> otherdocdocumentelipse;  
           otherdocdocumentelipse [label="...other\ndocuments"];
   docs -> submodules
   
   masterindex -> releasedocumentindex [style=dashed, label="sphinx\ntoctree\nreference"];
   
   //Show submodule linkage to docs directory
   submodules -> reponamesm [style=dotted,label="git\nsubmodule\nreference"];  
                 reponamesm [label="reponame"];

   //Example Release document index that references component info provided in other project repo
   release -> releasedocumentindex;   
              releasedocumentindex [label="index.rst", shape=box];
   releasedocumentindex -> newrepodocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"];
 
   }

Creating Restructured Text
==========================

TODO Add simple example and references here

Links and References
====================
It's pretty common to want to reference another location in the
ONAP 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``.

Testing
=======

One RST File
------------
It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards.
To validate your rst files using doc8, install doc8.

.. code-block:: bash

   sudo pip install doc8

doc8 can now be used to check the rst files. Execute as,

.. code-block:: bash

   doc8 --ignore D000,D001 <file>



One Project
-----------
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 doc repository.

.. code-block:: bash

   git clone http://gerrit.onap.org/r/doc

Change directory to doc & install requirements.

.. code-block:: bash

   cd doc
   sudo pip install -r etc/requirements.txt

Move the conf.py file to your project folder where RST files have been kept:

.. code-block:: bash

   mv doc/docs/conf.py <path-to-your-folder>/

Move the static files to your project folder:

.. code-block:: bash

   mv docs/_static/ <path-to-your-folder>/

Build the documentation from within your project folder:

.. code-block:: bash

   sphinx-build -b html <path-to-your-folder> <path-to-output-folder>

Your documentation shall be built as HTML inside the
specified output folder directory.

.. note:: Be sure to remove the `conf.py`, the static/ files and the output folder from the `<project>/docs/`. This is for testing only. Only commit the rst files and related content.


All Documentation
-----------------
To build the whole documentation under doc/, follow these steps:

Install virtual environment.

.. code-block:: bash

   sudo pip install virtualenv
   cd /local/repo/path/to/project

Download the DOC repository.

.. code-block:: bash

   git clone http://gerrit.onap.org/r/doc

Change directory to docs & install requirements.

.. code-block:: bash

   cd doc
   sudo pip install -r etc/requirements.txt

Update submodules, build documentation using tox & then open using any browser.

.. code-block:: bash

   cd doc
   git submodule update --init
   tox -edocs
   firefox docs/_build/html/index.html

.. note:: Make sure to run `tox -edocs` and not just `tox`.