Added extra code and explanations + some fixes for enable_docu_gen.rst

JIRA: Added extra code and explanations + some fixes for enable_docu_gen.rst

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

1 files changed, 60 insertions, 45 deletions

diff --git a/docs/enable_docu_gen.rst b/docs/enable_docu_gen.rst
index a9cd01253..9e764bd03 100644
--- a/docs/enable_docu_gen.rst
+++ b/docs/enable_docu_gen.rst
@@ -19,68 +19,84 @@ How to setup the workflow of documentation build for your project
   a quick guide: http://docutils.sourceforge.net/docs/user/rst/quickref.html
 
 
-**Clone the releng repository so you can created jobs for JJB**
+**Clone the releng repository so you can created jobs for JJB**::
 
-git clone ssh://<username>@gerrit.opnfv.org:29418/releng
+ git clone ssh://<username>@gerrit.opnfv.org:29418/releng
 
-cd releng/jjb/<project>/
+Enter the project settings::
 
-Create build-docu.sh with the following content:
--------------------------------------------------
+ cd releng/jjb/<project>/
 
-``#!/bin/bash
-set -xv
-for file in $(find . -type f -iname '*.rst'); do
- file_cut="${{file%.*}}"
- html_file=$file_cut".html"
- pdf_file=$file_cut".pdf"
- rst2html $file > $html_file
- rst2pdf $file -o $pdf_file
-done``
 
+**Create build-docu.sh**
 
+The script is the same for most of the projects and you can just copy it under your project in releng/jjb/<project>/
 
-Edit <project>.yml and make sure you have the job-templates set as in the example below:
+example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/::
 
+ #!/bin/bash
+ set -xv
+ for file in $(find . -type f -iname '*.rst'); do
+  file_cut="${{file%.*}}"
+  html_file=$file_cut".html"
+  pdf_file=$file_cut".pdf"
+  rst2html $file > $html_file
+  rst2pdf $file -o $pdf_file
+ done
 
-``- job-template:
-    name: 'opnfvdocs-daily-{stream}'
-    <more code present>
-    builders:
-        - shell:
-            !include-raw build-docu.sh
-        - shell: |
-           gsutil cp docs/*.pdf gs://artifacts.opnfv.org/opnfvdocs/docs/
-           gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/
 
 
+**Edit <your-project>.yml**::
 
-- job-template:
-    name: 'opnfvdocs-verify'
-    <more code present>
-    builders:
-        - shell:
-            !include-raw build-docu.sh
+ vi releng/jjb/<your-project>/<your-project>.yml
 
 
+Make sure you have the job-templates set right
 
-- job-template:
-    name: 'opnfvdocs-merge'
-    <more code present>
-    builders:
-        - shell:
-            !include-raw build-docu.sh
-        - shell: |
-           gsutil cp docs/*.pdf gs://artifacts.opnfv.org/opnfvdocs/docs/
-           gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/``
+example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "builder" section)::
 
+ - job-template:
+        name: 'opnfvdocs-daily-{stream}'
+        ...
+        builders:
+                - shell:
+                        !include-raw build-docu.sh
+                - shell: |
+                        echo $PATH
+                        /usr/local/bin/gsutil cp docs/*.pdf gs://artifacts.opnfv.org/opnfvdocs/docs/
+                        /usr/local/bin/gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/
 
+ - job-template:
+        name: 'opnfvdocs-verify'
+        ...
+        builders:
+                - shell:
+                        !include-raw build-docu.sh
 
-git add  build-docu.sh <project>.yml
+ - job-template:
+        name: 'opnfvdocs-merge'
+        ...
+        builders:
+                - shell:
+                        !include-raw build-docu.sh
+                - shell: |
+                        /usr/local/bin/gsutil cp docs/*.pdf gs://artifacts.opnfv.org/opnfvdocs/docs/
+                /usr/local/bin/gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/
 
-git commit --signoff                              #add the proper message to commit
 
-git review -v
+Stage files::
+
+ git add  build-docu.sh <project>.yml
+
+Commit change with --signoff::
+
+ git commit --signoff
+
+
+Send code for review in Gerrit::
+
+ git review -v
+
 
 
 
@@ -129,15 +145,14 @@ if the Jenkins is CentOS/RHEL; many variants have been tested but this is the cl
       - takes some time to customize the output in matters of template, requires custom html header/footer
       - latex suite is quite substantial in amount of packages and consumed space (around 1.2 GB)
 
- Tested: roughly, functional tbeeingests only
+ Tested: roughly, functional tests only
 
 
 
 2. Maven & clouddocs-maven-plugin (actually used to generate openstack-manuals)
 --------------------------------------------------------------------------------
 
- Description: It represents the standard tool to generate Openstack documentation manuals, uses maven, maven plugins, clouddocs-maven-plugins; location of finally generated files is the object of a small
-Bash script that will reside as Post-actions
+ Description: It represents the standard tool to generate Openstack documentation manuals, uses maven, maven plugins, clouddocs-maven-plugins; location of finally generated files is the object of a small Bash script that will reside as Post-actions
 
  Input files: .xml