Merge "Add information on tox usage"

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

diff --git a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
index 8995991..af46d64 100644 (file)
--- a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
@@ -51,7 +51,10 @@ login to gerrit or for git clone requests over ssh.
 The next step is to 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::
 
@@ -427,12 +430,27 @@ One Project
 -----------
 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.
 
@@ -445,29 +463,32 @@ Change directory to doc & install requirements.
 .. code-block:: bash
 
    cd doc
-   sudo pip install -r etc/requirements.txt
+   pip install -r etc/requirements.txt
 
-Move the conf.py file to your project folder where RST files have been kept:
+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:
@@ -476,12 +497,11 @@ 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.
 
@@ -502,7 +522,7 @@ Build documentation using tox local environment & then open using any browser.
    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.