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://@gerrit.opnfv.org:29418/ cd **Inside the repository create the following structure:**:: gerrit.opnfv.org/ |-- docs/ | |-- some-project-description.rst | |-- other-doc-1.rst | |-- images/ | |-- *.png|*.jpg |-- release/ | |-- some-release-doc.rst | |-- images/ | |-- *.png|*.jpg |-- requirements/ | |-- requirements.rst | |-- images/ | |-- *.png|*.jpg |-- design_docs/ | |-- some-design-doc.rst | |-- images/ | |-- *.png|*.jpg |-- some_project_file.py |-- some_shell_script.sh |-- INFO `-- README More details about the default structure you can find `here `_ at paragraph "How and where to store the document content files in your repository". **In order to obtain a nice .html & .pdf at then end you must write you documentation using reSt markup** quick guides: * http://docutils.sourceforge.net/docs/user/rst/quickref.html * http://rest-sphinx-memo.readthedocs.org/en/latest/ReST.html * http://www.math.uiuc.edu/~gfrancis/illimath/windows/aszgard_mini/movpy-2.0.0-py2.4.4/manuals/docutils/ref/rst/directives.html An `nice online editor `_ 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. **Clone the releng repository so you can created jobs for JJB**:: git clone ssh://@gerrit.opnfv.org:29418/releng Enter the project settings:: cd releng/jjb// **Create the verify & build scripts** The scripts are the same for most projects and if you need customizations copy them under your project in releng/jjb//:: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb// and change according to you needs. If standard will suffice for you skip this step and jump to **Edit .yml**, **Variant 1 - standard** **docu-build.sh**: .. code-block:: bash #!/bin/bash set -e set -o pipefail project="$(git remote -v | head -n1 | awk '{{print $2}}' | sed -e 's,.*:$.*/$\?,,' -e 's/\.git$//')" export PATH=$PATH:/usr/local/bin/ git_sha1="$(git rev-parse HEAD)" docu_build_date="$(date)" files=() while read -r -d ''; do files+=("$REPLY") done < <(find * -type f -iname '*.rst' -print0) for file in "${{files[@]}}"; do file_cut="${{file%.*}}" gs_cp_folder="${{file_cut}}" # sed part # add one '_' at the end of each trigger variable; ex: _sha1 +'_' & _date + '_' on both of the lines below # they were added here without the '_'suffix to avoid sed replacement sed -i "s/_sha1/$git_sha1/g" $file sed -i "s/_date/$docu_build_date/g" $file # rst2html part echo "rst2html $file" rst2html --halt=2 $file | gsutil cp -L gsoutput.txt - \ gs://artifacts.opnfv.org/"$project"/"$gs_cp_folder".html gsutil setmeta -h "Content-Type:text/html" \ -h "Cache-Control:private, max-age=0, no-transform" \ gs://artifacts.opnfv.org/"$project"/"$gs_cp_folder".html cat gsoutput.txt rm -f gsoutput.txt echo "rst2pdf $file" rst2pdf $file -o - | gsutil cp -L gsoutput.txt - \ gs://artifacts.opnfv.org/"$project"/"$gs_cp_folder".pdf gsutil setmeta -h "Content-Type:application/pdf" \ -h "Cache-Control:private, max-age=0, no-transform" \ gs://artifacts.opnfv.org/"$project"/"$gs_cp_folder".pdf cat gsoutput.txt rm -f gsoutput.txt done images=() while read -r -d ''; do im