.. 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 -> DR [label = "Add new project repo as\ngit submodule" ];
DA <-- DR [label = "Merge" ];
PA -> PR [label = "Create in new project repo\ntop level directory and index.rst" ];
PR -> DA [label = "Add as Reviewer" ];
PR <-- DA [label = "Approve and Integrate" ];
PA <-- PR [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 doc project: a directory under doc/docs/submodules with the same path/name as the new project initialized as a git submodule.
.. code-block:: bash
reponame=<your_repo_name>
git clone ssh://<your_id>@gerrit.onap.org:29418/doc
cd doc
mkdir -p `dirname docs/submodules/$reponame`
git submodule add https://gerrit.onap.org/r/$reponame docs/submodules/$reponame
git submodule init docs/submodules/$reponame
git submodule update docs/submodules/$reponame
echo " $reponame <../submodules/$reponame/docs/index>" >> docs/release/repolist.rst
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
(2) clone, modify, and commit to the new project an initial: docs top
level directory; index.rst; any other intial content.
.. code-block:: bash
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
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 published 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}
{rank=same releasedocumentindex releaserepolist}
//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/" ];
doc [href="https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree"];
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\nindex.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 -> releaserepolist [style=dashed, label="sphinx\ntoctree\nreference"];
releaserepolist [label="repolist.rst", shape=box];
release -> releaserepolist;
releaserepolist -> 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`.