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 build-upload-docu.sh**
  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  #!/bin/bash
  56  project="functest"
  57  export PATH=$PATH:/usr/local/bin/
  58
  59  git_sha1="$(git rev-parse HEAD)"
  60  docu_build_date="$(date)"
  61
  62  files=()
  63  while read -r -d ''; do
  64          files+=("$REPLY")
  65  done < <(find * -type f -iname '*.rst' -print0)
  66
  67  for file in "${{files[@]}}"; do
  68
  69          file_cut="${{file%.*}}"
  70          gs_cp_folder="${{file_cut}}"
  71
  72          # sed part
  73          sed -i "s/_sha1_/$git_sha1/g" $file
  74          sed -i "s/_date_/$docu_build_date/g" $file
  75
  76          # rst2html part
  77          echo "rst2html $file"
  78          rst2html $file | gsutil cp -L gsoutput.txt - \
  79          gs://artifacts.opnfv.org/"$project"/"$gs_cp_folder".html
  80          gsutil setmeta -h "Content-Type:text/html" \
  81                         -h "Cache-Control:private, max-age=0, no-transform" \
  82                         gs://artifacts.opnfv.org/"$project"/"$gs_cp_folder".html
  83          cat gsoutput.txt
  84          rm -f gsoutput.txt
  85
  86          echo "rst2pdf $file"
  87          rst2pdf $file -o - | gsutil cp -L gsoutput.txt - \
  88          gs://artifacts.opnfv.org/"$project"/"$gs_cp_folder".pdf
  89          gsutil setmeta -h "Content-Type:application/pdf" \
  90                         -h "Cache-Control:private, max-age=0, no-transform" \
  91                         gs://artifacts.opnfv.org/"$project"/"$gs_cp_folder".pdf
  92          cat gsoutput.txt
  93          rm -f gsoutput.txt
  94
  95  done
  96
  97  #the double {{ in file_cut="${{file%.*}}" is to escape jjb's yaml
  98
  99
 100 **Create build-docu-verify.sh**::
 101
 102  #!/bin/bash
 103  project="opnfvdocs"
 104  export PATH=$PATH:/usr/local/bin/
 105
 106  git_sha1="$(git rev-parse HEAD)"
 107  docu_build_date="$(date)"
 108
 109  files=()
 110  while read -r -d ''; do
 111          files+=("$REPLY")
 112  done < <(find * -type f -iname '*.rst' -print0)
 113
 114  for file in "${{files[@]}}"; do
 115
 116          file_cut="${{file%.*}}"
 117          gs_cp_folder="${{file_cut}}"
 118
 119          # sed part
 120          sed -i "s/_sha1_/$git_sha1/g" $file
 121          sed -i "s/_date_/$docu_build_date/g" $file
 122
 123          # rst2html part
 124          echo "rst2html $file"
 125          rst2html $file > $file_cut".html"
 126
 127          echo "rst2pdf $file"
 128          rst2pdf $file -o $file_cut".pdf"
 129
 130  done
 131
 132  #the double {{ in file_cut="${{file%.*}}" is to escape jjb's yaml
 133
 134
 135 **Edit <your-project>.yml**::
 136
 137  vi releng/jjb/<your-project>/<your-project>.yml
 138
 139
 140 Make sure you have the job-templates set correctly as below.
 141
 142 example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "builder" sections)::
 143
 144  - job-template:
 145     name: 'opnfvdocs-daily-{stream}'
 146
 147     node: master
 148     ...
 149     builders:
 150         - shell:
 151             !include-raw build-upload-docu.sh
 152
 153  - job-template:
 154     name: 'opnfvdocs-verify'
 155
 156     node: master
 157     ...
 158     builders:
 159         - shell:
 160             !include-raw build-docu-verify.sh
 161
 162  - job-template:
 163     name: 'opnfvdocs-merge'
 164
 165     node: master
 166     ...
 167     builders:
 168         - shell:
 169             !include-raw build-upload-docu.sh
 170
 171
 172 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 "...".
 173 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.
 174
 175
 176 Stage files::
 177
 178  git add  build-docu.sh <project>.yml
 179
 180
 181 Commit change with --signoff::
 182
 183  git commit --signoff
 184
 185
 186 Send code for review in Gerrit::
 187
 188  git review -v
 189
 190
 191 Create the documentation using the recommended structure in your repository and submit to gerrit for review
 192
 193
 194 **Jenkins will take over and produce artifacts in the form of .html & .pdf**
 195
 196 Jenkins has the proper packages installed in order to produce the artifacts.
 197
 198
 199 **Artifacts are stored on Google Storage (still to decide where, structure and how to present them)**
 200
 201 http://artifacts.opnfv.org/
 202
 203
 204 `Here you can download the PDF version <http://artifacts.opnfv.org/opnfvdocs/docs/enable_docu_gen.pdf>`_ of this guide.
 205
 206
 207 **Scrape content from html artifacts on wiki**
 208
 209 This section describes how the html build artifacts can be made visible on Wiki using he scrape method.
 210 In order to have you documentation on Wiki you need to create a wiki page and include an adaption of the code below:
 211
 212 example::
 213
 214  {{scrape>http://artifacts.opnfv.org/opnfvdocs/docs/enable_docu_gen.html}}
 215
 216
 217 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.
 218
 219 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.
 220
 221
 222 **How to track documentation**
 223
 224 You must include at the bottom of every document that you want to track the following::
 225
 226  **Documentation tracking**
 227
 228  Revision: _sha1
 229
 230  Build date:  _date
 231
 232  # add one "_" at the end of each trigger variable (they have also a prefix "_") when inserting them into documents to enable auto-replacement
 233
 234
 235
 236 NOTE:
 237 ------
 238
 239 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.
 240 For html generation it also supports css styles if needed.
 241
 242
 243 **Documentation tracking**
 244
 245 Revision: _sha1_
 246
 247 Build date:  _date_
 248
 249