diff options
Diffstat (limited to 'docs/enable_docu_gen.rst')
| -rw-r--r-- | docs/enable_docu_gen.rst | 91 |
1 files changed, 74 insertions, 17 deletions
diff --git a/docs/enable_docu_gen.rst b/docs/enable_docu_gen.rst index f90ef5ea4..639ea4920 100644 --- a/docs/enable_docu_gen.rst +++ b/docs/enable_docu_gen.rst @@ -12,15 +12,28 @@ How to setup the workflow of automatic documentation build for your project **Inside the repository create the following structure:**:: - gerrit.opnfv.org/<project>/docs/some-project-description.rst - /other-doc-1.rst - /images/*.png|*.jpg - - docs/release/some-release-doc.rst - - requirements/requirements.rst - - design_docs/some-design-doc.rst + gerrit.opnfv.org/<project> + |-- 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 <https://wiki.opnfv.org/documentation>`_ at paragraph "How and where to store the document content files in your repository". @@ -48,9 +61,13 @@ Enter the project settings:: **Create the verify & build scripts** -The script is the same for most of the projects and you can just copy it under your project in releng/jjb/<project>/ +The scripts are the same for most projects and if you need customizations copy them under your project in releng/jjb/<project>/:: + + cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/ + +and change according to you needs. -example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/ +If standard will suffice for you skip this step and jump to **Edit <your-project>.yml**, **Variant 1 - standard** **docu-build.sh**:: @@ -80,7 +97,7 @@ example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/ # rst2html part echo "rst2html $file" - rst2html $file | gsutil cp -L gsoutput.txt - \ + 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" \ @@ -149,7 +166,7 @@ example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/ # rst2html part echo "rst2html $file" - rst2html $file > $file_cut".html" + rst2html --exit-status=2 $file > $file_cut".html" echo "rst2pdf $file" rst2pdf $file -o $file_cut".pdf" @@ -166,9 +183,49 @@ example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/ Make sure you have the job-templates set correctly as below. -example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "builder" sections) +example:: + vi releng/jjb/opnfvdocs/opnfvdocs.yml + # make sure you are using one of the variants below and that !include-raw directive is present + +Variant 1 - standard +--------------------- + +By chosing **Variant 1** you will use the scripts from opnfvdocs project. + +**<your-project>.yml**:: + + - job-template: + name: 'opnfvdocs-daily-{stream}' + + node: master + ... + builders: + - shell: + !include-raw ../opnfvdocs/docu-build.sh + + - job-template: + name: 'opnfvdocs-verify' + + node: master + ... + builders: + - shell: + !include-raw ../opnfvdocs/docu-verify.sh + + - job-template: + name: 'opnfvdocs-merge' + + node: master + ... + builders: + - shell: + !include-raw ../opnfvdocs/docu-build.sh + + +Variant 2 - custom +------------------- -**opnfvdocs.yml**:: +**<your-project>.yml**:: - job-template: name: 'opnfvdocs-daily-{stream}' @@ -204,9 +261,9 @@ Please reffer to the releng repository for the correct indentation as JJB is ver 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. -Stage files:: +Stage files example:: - git add build-docu.sh <project>.yml + git add docu-build.sh docu-verify.sh <project>.yml Commit change with --signoff:: |