diff options
| -rw-r--r-- | docs/enable_docu_gen.rst | 105 |
1 files changed, 60 insertions, 45 deletions
diff --git a/docs/enable_docu_gen.rst b/docs/enable_docu_gen.rst index a9cd01253..9e764bd03 100644 --- a/docs/enable_docu_gen.rst +++ b/docs/enable_docu_gen.rst @@ -19,68 +19,84 @@ How to setup the workflow of documentation build for your project a quick guide: http://docutils.sourceforge.net/docs/user/rst/quickref.html -**Clone the releng repository so you can created jobs for JJB** +**Clone the releng repository so you can created jobs for JJB**:: -git clone ssh://<username>@gerrit.opnfv.org:29418/releng + git clone ssh://<username>@gerrit.opnfv.org:29418/releng -cd releng/jjb/<project>/ +Enter the project settings:: -Create build-docu.sh with the following content: -------------------------------------------------- + cd releng/jjb/<project>/ -``#!/bin/bash -set -xv -for file in $(find . -type f -iname '*.rst'); do - file_cut="${{file%.*}}" - html_file=$file_cut".html" - pdf_file=$file_cut".pdf" - rst2html $file > $html_file - rst2pdf $file -o $pdf_file -done`` +**Create build-docu.sh** +The script is the same for most of the projects and you can just copy it under your project in releng/jjb/<project>/ -Edit <project>.yml and make sure you have the job-templates set as in the example below: +example: cp releng/jjb/opnfvdocs/build-docu.sh releng/jjb/<your-project>/:: + #!/bin/bash + set -xv + for file in $(find . -type f -iname '*.rst'); do + file_cut="${{file%.*}}" + html_file=$file_cut".html" + pdf_file=$file_cut".pdf" + rst2html $file > $html_file + rst2pdf $file -o $pdf_file + done -``- job-template: - name: 'opnfvdocs-daily-{stream}' - <more code present> - builders: - - shell: - !include-raw build-docu.sh - - shell: | - gsutil cp docs/*.pdf gs://artifacts.opnfv.org/opnfvdocs/docs/ - gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/ +**Edit <your-project>.yml**:: -- job-template: - name: 'opnfvdocs-verify' - <more code present> - builders: - - shell: - !include-raw build-docu.sh + vi releng/jjb/<your-project>/<your-project>.yml +Make sure you have the job-templates set right -- job-template: - name: 'opnfvdocs-merge' - <more code present> - builders: - - shell: - !include-raw build-docu.sh - - shell: | - gsutil cp docs/*.pdf gs://artifacts.opnfv.org/opnfvdocs/docs/ - gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/`` +example: less releng/jjb/opnfvdocs/opnfvdocs.yml (pay extra attention at the "builder" section):: + - job-template: + name: 'opnfvdocs-daily-{stream}' + ... + builders: + - shell: + !include-raw build-docu.sh + - shell: | + echo $PATH + /usr/local/bin/gsutil cp docs/*.pdf gs://artifacts.opnfv.org/opnfvdocs/docs/ + /usr/local/bin/gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/ + - job-template: + name: 'opnfvdocs-verify' + ... + builders: + - shell: + !include-raw build-docu.sh -git add build-docu.sh <project>.yml + - job-template: + name: 'opnfvdocs-merge' + ... + builders: + - shell: + !include-raw build-docu.sh + - shell: | + /usr/local/bin/gsutil cp docs/*.pdf gs://artifacts.opnfv.org/opnfvdocs/docs/ + /usr/local/bin/gsutil cp docs/*.html gs://artifacts.opnfv.org/opnfvdocs/docs/ -git commit --signoff #add the proper message to commit -git review -v +Stage files:: + + git add build-docu.sh <project>.yml + +Commit change with --signoff:: + + git commit --signoff + + +Send code for review in Gerrit:: + + git review -v + @@ -129,15 +145,14 @@ if the Jenkins is CentOS/RHEL; many variants have been tested but this is the cl - takes some time to customize the output in matters of template, requires custom html header/footer - latex suite is quite substantial in amount of packages and consumed space (around 1.2 GB) - Tested: roughly, functional tbeeingests only + Tested: roughly, functional tests only 2. Maven & clouddocs-maven-plugin (actually used to generate openstack-manuals) -------------------------------------------------------------------------------- - Description: It represents the standard tool to generate Openstack documentation manuals, uses maven, maven plugins, clouddocs-maven-plugins; location of finally generated files is the object of a small -Bash script that will reside as Post-actions + Description: It represents the standard tool to generate Openstack documentation manuals, uses maven, maven plugins, clouddocs-maven-plugins; location of finally generated files is the object of a small Bash script that will reside as Post-actions Input files: .xml |