Setting Up
==========
+ONAP documentation is stored in git repositories, changes are managed
+with gerrit reviews, and published documents generated when there is a
+change in any source used to build the documentation.
+
+Authors create source for documents in reStructured Text (RST) that is
+rendered to HTML and published on Readthedocs.io.
+The developer Wiki or other web sites can reference these rendered
+documents directly allowing projects to easily maintain current release
+documentation.
+
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
PA <-- PR [label = "Merge" ];
}
-Setup project repositories(s)
------------------------------
+Setup project repositories
+--------------------------
These steps are performed for each project repository that
provides documentation.
-First let's set two variables that will be used in the subsequent steps.
+1. Set two variables that will be used in the subsequent steps.
Set *reponame* to the project repository you are setting up
just as it appears in the **Project Name** column of
the Gerrit projects page.
reponame=
lfid=
-The next step is to add a directory in the doc project where your
+2. Add a directory in the doc project where your
project will be included as a submodule and at least one reference
from the doc project to the documentation index in your repository.
-The following sequence will do this over ssh.
+The following sequence will do this over ssh. Please note that the
+reference to your project in *repolist.rst* should be considered
+temporary and removed when you reference it from more appropriate
+place.
.. caution::
reference on changes and/or the verify job will fail in the step below.
-The last step is to create a docs directory in your repository with
+3. Create a docs directory in your repository with
an index.rst file. The following sequence will complete the minimum
required over ssh. As you have time to convert or add new content you
can update the index and add files under the docs folder.
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>`_.
+<http://www.sphinx-doc.org/en/stable/markup/inline.html>`_.
Within a single document, you can reference another section simply by::
-----------
To test how the documentation renders in HTML, follow these steps:
-Install virtual environment.
+Install `virtual environment <https://pypi.org/project/virtualenv>`_ & create one.
.. code-block:: bash
sudo pip install virtualenv
- cd /local/repo/path/to/project
+ virtualenv onap_docs
+
+Activate `onap_docs` virtual environment.
+
+.. code-block:: bash
+
+ source onap_docs/bin/activate
+
+.. note:: Virtual environment activation has to be performed before attempting to build documentation.
+ Otherwise, tools necessary for the process might not be available.
+
+Download a project repository.
+
+.. code-block:: bash
+
+ git clone http://gerrit.onap.org/r/<project>
Download the doc repository.
.. code-block:: bash
cd doc
- sudo pip install -r etc/requirements.txt
+ pip install -r etc/requirements.txt
+
+.. warning::
-Move the conf.py file to your project folder where RST files have been kept:
+ Just follow the next step (copying conf.py from Doc project to your project)
+ if that is your intention, otherwise skip it. Currently all projects should already have a conf.py file.
+ Through the next step, this file and potential extensions in your project get overriden.
+
+Copy 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>/
+ cp docs/conf.py <path-to-project-folder>/<folder where are rst files>
-Move the static files to your project folder:
+Copy the static files to the project folder where RST files have been kept:
.. code-block:: bash
- mv docs/_static/ <path-to-your-folder>/
+ cp -r docs/_static/ <path-to-project-folder>/<folder where are rst files>
Build the documentation from within your project folder:
.. code-block:: bash
- sphinx-build -b html <path-to-
your-folder> <path-to-output-folder>
+ sphinx-build -b html <path-to-
project-folder>/<folder where are rst files> <path-to-output-folder>
Your documentation shall be built as HTML inside the
specified output folder directory.
+You can use your Web Browser to open
+and check resulting html pages in the output folder.
+
.. 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.
.. _building-all-documentation:
-----------------
To build the all documentation under doc/, follow these steps:
-Install virtual environment.
+Install `tox <https://pypi.org/project/tox>`_.
.. code-block:: bash
- sudo pip install virtualenv
- cd /local/repo/path/to/project
+ sudo pip install tox
Download the DOC repository.
by the doc project.
There are additional tox environment options for checking External
-URLs and Spelling. Use the tox environment options below and then
+URLs and Spelling. Use the tox environment options below and then
look at the output with the Linux `more` or similar command
scan for output that applies to the files you are validating.
Code Review / doc.git / blobdiff