docs/enable_docu_gen.rst

   1 How to setup the workflow of automatic documentation build for your project
   2 ----------------------------------------------------------------------------
   3
   4
   5 **Setup you repository and then clone locally**::
   6
   7  ssh-add your-ssh.key
   8
   9  git clone ssh://<username>@gerrit.opnfv.org:29418/<project>
  10
  11  cd <project>
  12
  13
  14 **Inside the repository create the following structure:**::
  15
  16    gerrit.opnfv.org/<project> - docs/
  17                                     /main.rst
  18                                     /other-docus.rst
  19                                     /images/*.png|*.jpg
  20
  21
  22 **In order to obtain a nice .html & .pdf at then end you must write you documentation using reSt markup**
  23
  24 quick guide: http://docutils.sourceforge.net/docs/user/rst/quickref.html
  25
  26
  27 **Clone the releng repository so you can created jobs for JJB**::
  28
  29  git clone ssh://<username>@gerrit.opnfv.org:29418/releng
  30
  31
  32 Enter the project settings::
  33
  34  cd releng/jjb/<project>/
  35
  36
  37 **Create build-docu.sh**
  38
  39 The script is the same for most of the projects and you can just copy it under your project in releng/jjb/<project>/
  40
  41 example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/::
  42
  43  #!/bin/bash
  44  set -xv
  45  for file in $(find . -type f -iname '*.rst'); do
  46         file_cut="${{file%.*}}"
  47         html_file=$file_cut".html"
  48         pdf_file=$file_cut".pdf"
  49         rst2html $file > $html_file
  50         rst2pdf $file -o $pdf_file
  51  done
  52
  53
  54  #the double {{ in file_cut="${{file%.*}}" is to escape jjb's yaml
  55
  56
  57
  58 **Edit <your-project>.yml**::
  59
  60  vi releng/jjb/<your-project>/<your-project>.yml
  61
  62
  63 Make sure you have the job-templates set right
  64
  65 example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "builder" sections)::
  66
  67  - job-template:
  68         name: 'opnfvdocs-daily-{stream}'
  69         ...
  70         builders:
  71                 - shell:
  72                         !include-raw build-docu.sh
  73                 - shell: |
  74                         echo $PATH
  75                         /usr/local/bin/gsutil cp docs/*.pdf gs://artifacts.opnfv.org/opnfvdocs/docs/
  76                         /usr/local/bin/gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/
  77
  78
  79  - job-template:
  80         name: 'opnfvdocs-verify'
  81         ...
  82         builders:
  83                 - shell:
  84                         !include-raw build-docu.sh
  85
  86
  87  - job-template:
  88         name: 'opnfvdocs-merge'
  89         ...
  90         builders:
  91                 - shell:
  92                         !include-raw build-docu.sh
  93                 - shell: |
  94                         /usr/local/bin/gsutil cp docs/*.pdf gs://artifacts.opnfv.org/opnfvdocs/docs/
  95                 /usr/local/bin/gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/
  96
  97
  98
  99 Stage files::
 100
 101  git add  build-docu.sh <project>.yml
 102
 103 Commit change with --signoff::
 104
 105  git commit --signoff
 106
 107
 108 Send code for review in Gerrit::
 109
 110  git review -v
 111
 112
 113
 114
 115 **Create the documentation using the recommended structure in your repository and submit to gerrit for review**
 116
 117
 118 **Jenkins will take over and produce artifacts in the form of .html & .pdf**
 119
 120 Jenkins has the proper packages installed in order to produce the artifacts.
 121
 122
 123 **Artifacts are stored on Google Storage (still to decide where, structure and how to present them)**
 124
 125 http://artifacts.opnfv.org/
 126
 127 example: http://artifacts.opnfv.org/opnfvdocs/docs/enable_docu_gen.pdf
 128
 129
 130 **Scrape content from html artifacts on wiki**
 131
 132 example of what you sould write on wiki, below::
 133
 134  {{scrape>http://artifacts.opnfv.org/opnfvdocs/docs/enable_docu_gen.html}}
 135
 136
 137 NOTE:
 138 ------
 139
 140 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.
 141
 142
 143
 144
 145 **Other options to generate documentation that we tested:**
 146
 147
 148 **Doxygen plugin -> HTML published plugin (html)/ LaTeX (pdf)**
 149
 150
 151 Description: This was the first discovered method
 152
 153 - html: using Doxygen plugin + HTML publisher
 154   It involves some customization at doxygen level + custom html header/footer
 155
 156 - pdf: it generates a .pdf using latex
 157
 158 - Input files: .md , .rst
 159
 160 - Output: .html & .pdf
 161
 162 - Pros:
 163
 164       - standard tools: doxygen, html publisher, LaTeX suite
 165       - doxygen plugin available in Jenkins, you just need to install it; html publisher plugin available in Jenkins, you just need to install it
 166       - destination files are generated fast
 167       - standard reStructuredText or Markdown
 168
 169 - Cons:
 170
 171       - takes some time to customize the output in matters of template, requires custom html header/footer
 172       - latex suite is quite substantial in amount of packages and consumed space (around 1.2 GB)
 173
 174 - Tested: roughly, functional tests only
 175
 176
 177
 178 **Maven & clouddocs-maven-plugin (actually used to generate openstack-manuals)**
 179
 180
 181 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
 182
 183 - Input files: .xml
 184
 185 - Output: .html & .pdf
 186
 187 - Pros:
 188
 189       - quite easy for initial setup
 190       - uses openstack documentation generation flows as for openstack-manuals (clouddocs-maven-plugin), maven installs all you need generate the documentation
 191
 192 - Cons:
 193
 194       - could be tricky to generate a custom layout, knowledge about Maven plugins required, .pom editing
 195       - dependent of multiple maven plugins
 196       - input files are .xml and xml editing knowledge is required
 197
 198 - Tested: roughly, functional tests only
 199
 200
 201
 202 **Sphinx & LaTeX suite**
 203
 204
 205 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
 206
 207 - Input files: .rst as default
 208
 209 - Output: .html & .pdf
 210
 211 - Pros:
 212
 213       - standard tools: Python Sphinx, LaTeX suite
 214       - destination files are generated fast
 215       - standard reStructuredText as default; other inputs can be configured
 216       - Sphinx's installation is very clean in matters of folder structure; the cleanest from all tested variants
 217       - latex suite is also easy to install via yum/apt and available in general repos
 218       - everyone is migration from other tools to Spinx lately; it provides more control and better looking documentation
 219       - can be used also for source-code documentation, specially if you use Python
 220
 221 - Cons:
 222
 223       - takes some time to customize the output in matters of template, requires custom html header/footer
 224       - latex suite is quite substantial in amount of packages and consumed space (around 1.2 GB)
 225
 226 - Tested: roughly, functional tests only
 227
 228