summaryrefslogtreecommitdiffstats
path: root/docs/enable_docu_gen.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/enable_docu_gen.rst')
-rw-r--r--docs/enable_docu_gen.rst91
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::