Update docs/enable_docu_gen.rst scripts to include "rst2html --halt=warning"

JIRA: DOCS-32 - Update docs/enable_docu_gen.rst scripts to include "rst2html --halt=warning"
and added a more clear tree structure for repository

Change-Id: Iaabce4dcb04464cae1ec6404a6e86aee275e339c
Signed-off-by: Victor Laza <vlaza@cloudbasesolutions.com>

1 files changed, 74 insertions, 17 deletions

diff --git a/docs/enable_docu_gen.rst b/docs/enable_docu_gen.rst
index f90ef5ea4..639ea4920 100644
--- a/docs/enable_docu_gen.rst
+++ b/docs/enable_docu_gen.rst
@@ -12,15 +12,28 @@ How to setup the workflow of automatic documentation build for your project
 
 **Inside the repository create the following structure:**::
 
-   gerrit.opnfv.org/<project>/docs/some-project-description.rst
-                                  /other-doc-1.rst
-                                  /images/*.png|*.jpg
-
-                              docs/release/some-release-doc.rst
-
-                              requirements/requirements.rst
-
-                              design_docs/some-design-doc.rst
+   gerrit.opnfv.org/<project>
+                        |-- docs/
+                        |    |-- some-project-description.rst
+                        |    |-- other-doc-1.rst
+                        |    |-- images/
+                        |         |-- *.png|*.jpg
+                        |-- release/
+                        |    |-- some-release-doc.rst
+                        |    |-- images/
+                        |         |-- *.png|*.jpg
+                        |-- requirements/
+                        |    |-- requirements.rst
+                        |    |-- images/
+                        |         |-- *.png|*.jpg
+                        |-- design_docs/
+                        |    |-- some-design-doc.rst
+                        |    |-- images/
+                        |         |-- *.png|*.jpg
+                        |-- some_project_file.py
+                        |-- some_shell_script.sh
+                        |-- INFO
+                        `-- README
 
 
 More details about the default structure you can find `here <https://wiki.opnfv.org/documentation>`_ at paragraph "How and where to store the document content files in your repository".
@@ -48,9 +61,13 @@ Enter the project settings::
 
 **Create the verify & build scripts**
 
-The script is the same for most of the projects and you can just copy it under your project in releng/jjb/<project>/
+The scripts are the same for most projects and if you need customizations copy them under your project in releng/jjb/<project>/::
+
+ cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/
+
+and change according to you needs.
 
-example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/
+If standard will suffice for you skip this step and jump to **Edit <your-project>.yml**, **Variant 1 - standard**
 
 **docu-build.sh**::
 
@@ -80,7 +97,7 @@ example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/
 
          # rst2html part
          echo "rst2html $file"
-         rst2html $file | gsutil cp -L gsoutput.txt - \
+         rst2html --halt=2 $file | gsutil cp -L gsoutput.txt - \
          gs://artifacts.opnfv.org/"$project"/"$gs_cp_folder".html
          gsutil setmeta -h "Content-Type:text/html" \
                         -h "Cache-Control:private, max-age=0, no-transform" \
@@ -149,7 +166,7 @@ example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/
 
          # rst2html part
          echo "rst2html $file"
-         rst2html $file > $file_cut".html"
+         rst2html --exit-status=2 $file > $file_cut".html"
 
          echo "rst2pdf $file"
          rst2pdf $file -o $file_cut".pdf"
@@ -166,9 +183,49 @@ example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/
 
 Make sure you have the job-templates set correctly as below.
 
-example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "builder" sections)
+example::
+ vi releng/jjb/opnfvdocs/opnfvdocs.yml
+ # make sure you are using one of the variants below and that !include-raw directive is present
+
+Variant 1 - standard
+---------------------
+
+By chosing **Variant 1** you will use the scripts from opnfvdocs project.
+
+**<your-project>.yml**::
+
+ - job-template:
+    name: 'opnfvdocs-daily-{stream}'
+
+    node: master
+    ...
+    builders:
+        - shell:
+            !include-raw ../opnfvdocs/docu-build.sh
+
+ - job-template:
+    name: 'opnfvdocs-verify'
+
+    node: master
+    ...
+    builders:
+        - shell:
+            !include-raw ../opnfvdocs/docu-verify.sh
+
+ - job-template:
+    name: 'opnfvdocs-merge'
+
+    node: master
+    ...
+    builders:
+        - shell:
+            !include-raw ../opnfvdocs/docu-build.sh
+
+
+Variant 2 - custom
+-------------------
 
-**opnfvdocs.yml**::
+**<your-project>.yml**::
 
  - job-template:
     name: 'opnfvdocs-daily-{stream}'
@@ -204,9 +261,9 @@ Please reffer to the releng repository for the correct indentation as JJB is ver
 Also you must have your documentation under docs/ in the repository or gsutil will fail to copy them; for customizations you might need to addapt build-docu.sh as we did for genesis project as different documents need to go into different places.
 
 
-Stage files::
+Stage files example::
 
- git add  build-docu.sh <project>.yml
+ git add docu-build.sh docu-verify.sh <project>.yml
 
 
 Commit change with --signoff::