Add information on virtualenv usage

This patch also adds link to Python Package Index (like for doc8
package), drops no longer necessary privilege elevation and fixes minor
spacing issues.

Issue-ID: DOC-502
Change-Id: I55a583bf05a731371008d9cfb55cbfa2e2ad3a77
Signed-off-by: Pawel Wieczorek <p.wieczorek2@samsung.com>

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 6909cce..d61cb9c 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
@@ -427,17 +427,27 @@ One Project
 -----------
 To test how the documentation renders in HTML, follow these steps:
 
 -----------
 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
 
 .. code-block:: bash
 
    sudo pip install virtualenv

+   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
 
 
 Download a project repository.
 
 .. code-block:: bash
 

-  git clone http://gerrit.onap.org/r/<project>
+   git clone http://gerrit.onap.org/r/<project>

 
 Download the doc repository.
 
 
 Download the doc repository.
 


@@ -450,7 +460,7 @@ Change directory to doc & install requirements.
 .. code-block:: bash
 
    cd doc
 .. code-block:: bash
 
    cd doc

-   sudo pip install -r etc/requirements.txt
+   pip install -r etc/requirements.txt

 
 Copy 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:
 


@@ -476,7 +486,7 @@ specified output folder directory.
 You can use your Web Browser to open
 and check resulting html pages in the output folder.
 
 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.
+.. 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:
 
 
 .. _building-all-documentation: