Cosmetical operations in enable_docu_gen.rst to make a better looking document

JIRA: Cosmetical operations in enable_docu_gen.rst to make a better looking document:
rearanged some paragraphs, cleaner embedded code, scrape example

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

1 files changed, 72 insertions, 46 deletions

diff --git a/docs/enable_docu_gen.rst b/docs/enable_docu_gen.rst
index 9e764bd03..c3b44956e 100644
--- a/docs/enable_docu_gen.rst
+++ b/docs/enable_docu_gen.rst
@@ -1,28 +1,34 @@
-How to setup the workflow of documentation build for your project
-==================================================================
+How to setup the workflow of automatic documentation build for your project
+----------------------------------------------------------------------------
 
-**Setup you repository and then clone locally**
 
-   ssh-add your-ssh-key
-   git clone ssh://<username>@gerrit.opnfv.org:29418/<project>
+**Setup you repository and then clone locally**::
 
+ ssh-add your-ssh.key
+
+ git clone ssh://<username>@gerrit.opnfv.org:29418/<project>
+
+ cd <project>
+
+
+**Inside the repository create the following structure:**::
 
-**Inside the repository create the following structure:**
    gerrit.opnfv.org/<project> - docs/
-                                               --- docs/main.rst
-                                               --- docs/other-docus.rst
-                                               --- docs/images/*.png|*.jpg
+                                    /main.rst
+                                    /other-docus.rst
+                                    /images/*.png|*.jpg
 
 
 **In order to obtain a nice .html & .pdf at then end you must write you documentation using reSt markup**
 
-  a quick guide: http://docutils.sourceforge.net/docs/user/rst/quickref.html
+quick guide: http://docutils.sourceforge.net/docs/user/rst/quickref.html
 
 
 **Clone the releng repository so you can created jobs for JJB**::
 
  git clone ssh://<username>@gerrit.opnfv.org:29418/releng
 
+
 Enter the project settings::
 
  cd releng/jjb/<project>/
@@ -37,13 +43,16 @@ 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
+        file_cut="${{file%.*}}"
+        html_file=$file_cut".html"
+        pdf_file=$file_cut".pdf"
+        rst2html $file > $html_file
+        rst2pdf $file -o $pdf_file
  done
 
+ 
+ #the double {{ in file_cut="${{file%.*}}" is to escape jjb's yaml
+
 
 
 **Edit <your-project>.yml**::
@@ -53,7 +62,7 @@ example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/::
 
 Make sure you have the job-templates set right
 
-example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "builder" section)::
+example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "builder" sections)::
 
  - job-template:
         name: 'opnfvdocs-daily-{stream}'
@@ -66,6 +75,7 @@ example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "bu
                         /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'
         ...
@@ -73,6 +83,7 @@ example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "bu
                 - shell:
                         !include-raw build-docu.sh
 
+
  - job-template:
         name: 'opnfvdocs-merge'
         ...
@@ -84,6 +95,7 @@ example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "bu
                 /usr/local/bin/gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/
 
 
+
 Stage files::
 
  git add  build-docu.sh <project>.yml
@@ -102,87 +114,101 @@ Send code for review in Gerrit::
 
 **Create the documentation using the recommended structure in your repository and submit to gerrit for review**
 
+
 **Jenkins will take over and produce artifacts in the form of .html & .pdf**
+
 Jenkins has the proper packages installed in order to produce the artifacts.
 
+
 **Artifacts are stored on Google Storage (still to decide where, structure and how to present them)**
 
+http://artifacts.opnfv.org/
 
+example: http://artifacts.opnfv.org/opnfvdocs/docs/enable_docu_gen.pdf
 
-**NOTE:** In order to generate html & pdf documentation the needed packages are rst2pdf & python-docutils 
-if the Jenkins is CentOS/RHEL; many variants have been tested but this is the cleanest as a solution.
 
+**Scrape content from html artifacts on wiki**
 
+example of what you sould write on wiki, below::
 
-**Other options:**
+ {{scrape>http://artifacts.opnfv.org/opnfvdocs/docs/enable_docu_gen.html}}
 
 
-1. Doxygen plugin -> HTML published plugin (html)/ LaTeX (pdf)
----------------------------------------------------------------
+NOTE:
+------
 
- Description:
+In order to generate html & pdf documentation the needed packages are rst2pdf & python-docutils if the Jenkins is CentOS/RHEL; many variants have been tested but this is the cleanest as a solution.
+
+
+
+
+**Other options to generate documentation that we tested:**
+
+
+**Doxygen plugin -> HTML published plugin (html)/ LaTeX (pdf)**
+
+
+Description: This was the first discovered method
 
 - html: using Doxygen plugin + HTML publisher
   It involves some customization at doxygen level + custom html header/footer
 
- - pdf: it generates a .pdf using latex
-
- Final destination of generated files needs to be discussed as it will be part of a Bash script in Post-actions.
+- pdf: it generates a .pdf using latex
 
- Input files: .md , .rst
+- Input files: .md , .rst
 
- Output: .html & .pdf
+- Output: .html & .pdf
 
- Pros:
+- Pros:
 
       - standard tools: doxygen, html publisher, LaTeX suite
       - doxygen plugin available in Jenkins, you just need to install it; html publisher plugin available in Jenkins, you just need to install it
       - destination files are generated fast
       - standard reStructuredText or Markdown
 
- Cons:
+- Cons:
 
       - 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 tests only
+- Tested: roughly, functional tests only
 
 
 
-2. Maven & clouddocs-maven-plugin (actually used to generate openstack-manuals)
---------------------------------------------------------------------------------
+**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
 
- Input files: .xml
+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
 
- Output: .html & .pdf
+- Input files: .xml
 
- Pros:
+- Output: .html & .pdf
+
+- Pros:
 
       - quite easy for initial setup
       - uses openstack documentation generation flows as for openstack-manuals (clouddocs-maven-plugin), maven installs all you need generate the documentation
 
- Cons:
+- Cons:
 
       - could be tricky to generate a custom layout, knowledge about Maven plugins required, .pom editing
       - dependent of multiple maven plugins
       - input files are .xml and xml editing knowledge is required
 
- Tested: roughly, functional tests only
+- Tested: roughly, functional tests only
+
 
 
+**Sphinx & LaTeX suite**
 
-3. Sphinx & LaTeX suite
-------------------------
 
- Description: The easiest to install, the cleanest in matter of folder & files structure, uses standard tools available in repositories; location of finally generated files is the object of a small Bash script that will reside as Post-actions
+Description: The easiest to install, the cleanest in matter of folder & files structure, uses standard tools available in repositories; location of finally generated files is the object of a small Bash script that will reside as Post-actions
 
- Input files: .rst as default
+- Input files: .rst as default
 
- Output: .html & .pdf
+- Output: .html & .pdf
 
- Pros:
+- Pros:
 
       - standard tools: Python Sphinx, LaTeX suite
       - destination files are generated fast
@@ -192,11 +218,11 @@ if the Jenkins is CentOS/RHEL; many variants have been tested but this is the cl
       - everyone is migration from other tools to Spinx lately; it provides more control and better looking documentation
       - can be used also for source-code documentation, specially if you use Python
 
- Cons:
+- Cons:
 
       - 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 tests only
+- Tested: roughly, functional tests only