docs/enable_docu_gen.rst

   1 How to setup the workflow of automatic documentation build for your project
   2 ----------------------------------------------------------------------------
   3
   4 **Setup you repository and then clone locally**::
   5
   6  ssh-add your-ssh.key
   7
   8  git clone ssh://<username>@gerrit.opnfv.org:29418/<project>
   9
  10  cd <project>
  11
  12
  13 **Inside the repository create the following structure:**::
  14
  15    gerrit.opnfv.org/<project>/docs/some-project-description.rst
  16                                   /other-doc-1.rst
  17                                   /images/*.png|*.jpg
  18
  19                               docs/release/some-release-doc.rst
  20
  21                               requirements/requirements.rst
  22
  23                               design_docs/some-design-doc.rst
  24
  25
  26 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".
  27
  28 **In order to obtain a nice .html & .pdf at then end you must write you documentation using reSt markup**
  29
  30 quick guides:
  31
  32 * http://docutils.sourceforge.net/docs/user/rst/quickref.html
  33 * http://rest-sphinx-memo.readthedocs.org/en/latest/ReST.html
  34 * http://www.math.uiuc.edu/~gfrancis/illimath/windows/aszgard_mini/movpy-2.0.0-py2.4.4/manuals/docutils/ref/rst/directives.html
  35
  36 An `nice online editor <http://rst.ninjs.org/>`_ that will help you write reSt and see your changes live. After done editing you can copy the source document in the repository and follow the workflow.
  37
  38
  39 **Clone the releng repository so you can created jobs for JJB**::
  40
  41  git clone ssh://<username>@gerrit.opnfv.org:29418/releng
  42
  43
  44 Enter the project settings::
  45
  46  cd releng/jjb/<project>/
  47
  48
  49 **Create the verify & build scripts**
  50
  51 The script is the same for most of the projects and you can just copy it under your project in releng/jjb/<project>/
  52
  53 example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/
  54
  55 **docu-build.sh**::
  56
  57  #!/bin/bash
  58  set -e
  59  set -o pipefail
  60
  61  project="$(git remote -v | head -n1 | awk '{{print $2}}' | sed -e 's,.*:\(.*/\)\?,,' -e 's/\.git$//')"
  62  export PATH=$PATH:/usr/local/bin/
  63
  64  git_sha1="$(git rev-parse HEAD)"
  65  docu_build_date="$(date)"
  66
  67  files=()
  68  while read -r -d ''; do
  69          files+=("$REPLY")
  70  done < <(find * -type f -iname '*.rst' -print0)
  71
  72  for file in "${{files[@]}}"; do
  73
  74          file_cut="${{file%.*}}"
  75          gs_cp_folder="${{file_cut}}"
  76
  77          # sed part
  78          sed -i "s/_sha1_/$git_sha1/g" $file
  79          sed -i "s/_date_/$docu_build_date/g" $file
  80
  81          # rst2html part
  82          echo "rst2html $file"
  83          rst2html $file | gsutil cp -L gsoutput.txt - \
  84          gs://artifacts.opnfv.org/"$project"/"$gs_cp_folder".html
  85          gsutil setmeta -h "Content-Type:text/html" \
  86                         -h "Cache-Control:private, max-age=0, no-transform" \
  87                         gs://artifacts.opnfv.org/"$project"/"$gs_cp_folder".html
  88          cat gsoutput.txt
  89          rm -f gsoutput.txt
  90
  91          echo "rst2pdf $file"
  92          rst2pdf $file -o - | gsutil cp -L gsoutput.txt - \
  93          gs://artifacts.opnfv.org/"$project"/"$gs_cp_folder".pdf
  94          gsutil setmeta -h "Content-Type:application/pdf" \
  95                         -h "Cache-Control:private, max-age=0, no-transform" \
  96                         gs://artifacts.opnfv.org/"$project"/"$gs_cp_folder".pdf
  97          cat gsoutput.txt
  98          rm -f gsoutput.txt
  99
 100  done
 101
 102  images=()
 103  while read -r -d ''; do
 104          images+=("$REPLY")
 105  done < <(find * -type f \( -iname \*.jpg -o -iname \*.png \) -print0)
 106
 107  for img in "${{images[@]}}"; do
 108
 109          # uploading found images
 110          echo "uploading $img"
 111          cat "$img" | gsutil cp -L gsoutput.txt - \
 112          gs://artifacts.opnfv.org/"$project"/"$img"
 113          gsutil setmeta -h "Content-Type:image/jpeg" \
 114                          -h "Cache-Control:private, max-age=0, no-transform" \
 115                          gs://artifacts.opnfv.org/"$project"/"$img"
 116          cat gsoutput.txt
 117          rm -f gsoutput.txt
 118
 119  done
 120
 121  #the double {{ in file_cut="${{file%.*}}" is to escape jjb's yaml
 122
 123
 124 **docu-verify.sh**::
 125
 126  #!/bin/bash
 127  set -e
 128  set -o pipefail
 129
 130  project="$(git remote -v | head -n1 | awk '{{print $2}}' | sed -e 's,.*:\(.*/\)\?,,' -e 's/\.git$//')"
 131  export PATH=$PATH:/usr/local/bin/
 132
 133  git_sha1="$(git rev-parse HEAD)"
 134  docu_build_date="$(date)"
 135
 136  files=()
 137  while read -r -d ''; do
 138          files+=("$REPLY")
 139  done < <(find * -type f -iname '*.rst' -print0)
 140
 141  for file in "${{files[@]}}"; do
 142
 143          file_cut="${{file%.*}}"
 144          gs_cp_folder="${{file_cut}}"
 145
 146          # sed part
 147          sed -i "s/_sha1_/$git_sha1/g" $file
 148          sed -i "s/_date_/$docu_build_date/g" $file
 149
 150          # rst2html part
 151          echo "rst2html $file"
 152          rst2html $file > $file_cut".html"
 153
 154          echo "rst2pdf $file"
 155          rst2pdf $file -o $file_cut".pdf"
 156
 157  done
 158
 159  #the double {{ in file_cut="${{file%.*}}" is to escape jjb's yaml
 160
 161
 162 **Edit <your-project>.yml**::
 163
 164  vi releng/jjb/<your-project>/<your-project>.yml
 165
 166
 167 Make sure you have the job-templates set correctly as below.
 168
 169 example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "builder" sections)
 170
 171 **opnfvdocs.yml**::
 172
 173  - job-template:
 174     name: 'opnfvdocs-daily-{stream}'
 175
 176     node: master
 177     ...
 178     builders:
 179         - shell:
 180             !include-raw docu-build.sh
 181
 182  - job-template:
 183     name: 'opnfvdocs-verify'
 184
 185     node: master
 186     ...
 187     builders:
 188         - shell:
 189             !include-raw docu-verify.sh
 190
 191  - job-template:
 192     name: 'opnfvdocs-merge'
 193
 194     node: master
 195     ...
 196     builders:
 197         - shell:
 198             !include-raw docu-build.sh
 199
 200
 201 "node: master" is important here as all documentations are built on Jenkins master node for now.
 202
 203 Please reffer to the releng repository for the correct indentation as JJB is very picky with those and also for the rest of the code that is missing in the example code and replaced by "...".
 204 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.
 205
 206
 207 Stage files::
 208
 209  git add  build-docu.sh <project>.yml
 210
 211
 212 Commit change with --signoff::
 213
 214  git commit --signoff
 215
 216
 217 Send code for review in Gerrit::
 218
 219  git review -v
 220
 221
 222 Create the documentation using the recommended structure in your repository and submit to gerrit for review
 223
 224
 225 **Jenkins will take over and produce artifacts in the form of .html & .pdf**
 226
 227 Jenkins has the proper packages installed in order to produce the artifacts.
 228
 229
 230 **Artifacts are stored on Google Storage (still to decide where, structure and how to present them)**
 231
 232 http://artifacts.opnfv.org/
 233
 234
 235 `Here you can download the PDF version <http://artifacts.opnfv.org/opnfvdocs/docs/enable_docu_gen.pdf>`_ of this guide.
 236
 237
 238 **Scrape content from html artifacts on wiki**
 239
 240 This section describes how the html build artifacts can be made visible on Wiki using he scrape method.
 241 In order to have you documentation on Wiki you need to create a wiki page and include an adaption of the code below:
 242
 243 example::
 244
 245  {{scrape>http://artifacts.opnfv.org/opnfvdocs/docs/enable_docu_gen.html}}
 246
 247
 248 Please try to write documentation as accurate and clear as possible as once reviewed and merged it will be automatically built and displayed on Wiki and everyone would apreciate a good written/nice looking guide.
 249
 250 If you want to see on wiki what code is scraped from the built artifacts click "Show pagesource" in the right (it will appear if you hover over the magnifier icon); this way you know what is written straight on wiki and what is embedded with "scrape". By knowing these details you will be able to prevent damages by manually updating wiki.
 251
 252
 253 **How to track documentation**
 254
 255 You must include at the bottom of every document that you want to track the following::
 256
 257  **Documentation tracking**
 258
 259  Revision: _sha1
 260
 261  Build date:  _date
 262
 263  # add one "_" at the end of each trigger variable (they have also a prefix "_") when inserting them into documents to enable auto-replacement
 264
 265
 266 **Image inclusion for artifacts**
 267
 268 Create a folder called images in the same folder where you documentation resides and copy .jpg or .png files there, according to the guide here: https://wiki.opnfv.org/documentation
 269
 270 Here is an example of what you need to include in the .rst files to include an image::
 271
 272  .. image:: images/smiley.png
 273     :height: 200
 274     :width: 200
 275     :alt: Just a smiley face!
 276     :align: left
 277
 278 The image will be shown in both .html and .pdf resulting artifacts.
 279
 280
 281 NOTE:
 282 ------
 283
 284 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 solution found.
 285 For html generation it also supports css styles if needed.
 286
 287
 288 **Documentation tracking**
 289
 290 Revision: _sha1_
 291
 292 Build date:  _date_
 293
 294