diff options
| -rw-r--r-- | docs/etc/conf.py | 30 | ||||
| -rw-r--r-- | docs/how-to-use-docs/documentation-example.rst | 20 | ||||
| -rw-r--r-- | docs/how-to-use-docs/index.rst | 19 | ||||
| -rw-r--r-- | docs/jenkins-job-builder/index.rst | 13 | ||||
| -rw-r--r-- | docs/jenkins-job-builder/opnfv-jjb-usage.rst | 5 | ||||
| -rw-r--r-- | jjb/opnfv/opnfv-docs.yml | 7 | ||||
| -rw-r--r-- | jjb/releng-macros.yaml | 104 |
7 files changed, 101 insertions, 97 deletions
diff --git a/docs/etc/conf.py b/docs/etc/conf.py index 68e847ee9..6245cc069 100644 --- a/docs/etc/conf.py +++ b/docs/etc/conf.py @@ -1,29 +1,23 @@ -import datetime -import sys -import os +''' +Base configuration file for sphinx-build. -needs_sphinx = '1.3' +You can override this configuration by putting 'conf.py' in the document +directory (e.g. how-to-use-docs/conf.py). +''' -numfig = True +import datetime -source_suffix = '.rst' +needs_sphinx = '1.3' master_doc = 'index' pygments_style = 'sphinx' -html_use_index = False -html_logo = 'opnfv-logo.png' -pdf_documents = [('index', u'Copper', u'Copper Project', u'OPNFV')] -pdf_fit_mode = "shrink" -pdf_stylesheets = ['sphinx','kerning','a4'] -#latex_domain_indices = False -#latex_use_modindex = False +html_use_index = False +numfig = True +html_logo = '../etc/opnfv-logo.png' -latex_elements = { - 'printindex': '', -} -latex_logo = 'opnfv-logo.png' +latex_elements = {'printindex': ''} +latex_logo = '../etc/opnfv-logo.png' -project = u'Copper: Virtual Infrastructure Deployment Policies' copyright = u'%s, OPNFV' % datetime.date.today().year version = u'1.0.0' release = u'1.0.0' diff --git a/docs/how-to-use-docs/documentation-example.rst b/docs/how-to-use-docs/documentation-example.rst index 764b546c8..fd0563fda 100644 --- a/docs/how-to-use-docs/documentation-example.rst +++ b/docs/how-to-use-docs/documentation-example.rst @@ -1,5 +1,3 @@ -.. two dots create a comment. please leave this logo at the top of each of your rst files. - How to create documentation for your OPNFV project ================================================== @@ -21,8 +19,9 @@ This index file must refence your other rst files. .. code-block:: bash - Example Documentation table of contents - ======================================= + ===================== + Example Documentation + ===================== Contents: @@ -32,10 +31,8 @@ This index file must refence your other rst files. documentation-example.rst - Indices and tables - ================== - - * :ref:`search` + .. + Leave these at the bottom of 'index.rst' file Revision: _sha1_ @@ -71,10 +68,3 @@ links are easy to add: Here is a link to sphinx, the tool that we are using to g .. code-block:: bash echo "Heres is a code block with bash syntax highlighting" - - -Leave these at the bottom of each of your documents they are used internally - -Revision: _sha1_ - -Build date: |today| diff --git a/docs/how-to-use-docs/index.rst b/docs/how-to-use-docs/index.rst index 2d493318d..0965eb3cd 100644 --- a/docs/how-to-use-docs/index.rst +++ b/docs/how-to-use-docs/index.rst @@ -1,12 +1,9 @@ -.. OPNFV Release Engineering documentation, created by - sphinx-quickstart on Tue Jun 9 19:12:31 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. + This is new template created on Thu Nov 26 16:18:09 JST 2015 -Example Documentation table of contents -======================================= - -Contents: +===================== +Example Documentation +===================== .. toctree:: :numbered: @@ -14,10 +11,8 @@ Contents: documentation-example.rst -Indices and tables -================== - -* :ref:`search` +.. + Leave these at the bottom of 'index.rst' file Revision: _sha1_ diff --git a/docs/jenkins-job-builder/index.rst b/docs/jenkins-job-builder/index.rst index 05847a1e0..f8f568339 100644 --- a/docs/jenkins-job-builder/index.rst +++ b/docs/jenkins-job-builder/index.rst @@ -1,24 +1,13 @@ -.. OPNFV Release Engineering documentation, created by - sphinx-quickstart on Tue Jun 9 19:12:31 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - +=========================== Release Engineering Project =========================== -Contents: - .. toctree:: :numbered: :maxdepth: 8 opnfv-jjb-usage.rst -Indices and tables -================== - -* :ref:`search` - Revision: _sha1_ Build date: |today| diff --git a/docs/jenkins-job-builder/opnfv-jjb-usage.rst b/docs/jenkins-job-builder/opnfv-jjb-usage.rst index 1945490f5..fa825c430 100644 --- a/docs/jenkins-job-builder/opnfv-jjb-usage.rst +++ b/docs/jenkins-job-builder/opnfv-jjb-usage.rst @@ -175,8 +175,3 @@ The Current merge and verify jobs for jenkins job builder as pulled from the rep cd /opt/jenkins-ci/releng git pull jenkins-jobs update --delete-old jjb/ - - -Revision: _sha1_ - -Build date: |today| diff --git a/jjb/opnfv/opnfv-docs.yml b/jjb/opnfv/opnfv-docs.yml index c6b6f8d8f..0cc9420db 100644 --- a/jjb/opnfv/opnfv-docs.yml +++ b/jjb/opnfv/opnfv-docs.yml @@ -74,8 +74,7 @@ pattern: 'docs/**' builders: - - build-html-and-pdf-docs-output - - upload-under-review-docs-to-opnfv-artifacts + - upload-review-docs - job-template: name: 'opnfv-docs-merge' @@ -123,6 +122,4 @@ pattern: 'docs/**' builders: - - build-html-and-pdf-docs-output - - upload-merged-docs-to-opnfv-artifacts - - remove-old-docs-from-opnfv-artifacts + - upload-merged-docs diff --git a/jjb/releng-macros.yaml b/jjb/releng-macros.yaml index 3be93c889..9a875a51f 100644 --- a/jjb/releng-macros.yaml +++ b/jjb/releng-macros.yaml @@ -157,12 +157,16 @@ [[ $GERRIT_CHANGE_NUMBER =~ .+ ]] - git_sha1="$(git rev-parse HEAD)" - - find docs/ -type f -iname '*.rst' -print0 | while read file - do - sed -i "s/_sha1_/$git_sha1/g" "$file" - done + _get_title_script=" + import os + from docutils import core + with open('index.rst', 'r') as file: + data = file.read() + doctree = core.publish_doctree(data, + settings_overrides={'report_level': 5, + 'halt_level': 5}) + print doctree[0].astext()" + _git_sha1="$(git rev-parse HEAD)" find docs/ -name 'index.rst' -printf '%h\n' | while read dir do @@ -176,16 +180,35 @@ echo "#################${dir//?/#}" echo - mkdir -p "$_output" + sed -i "s/_sha1_/$_git_sha1/g" "$dir/index.rst" - sphinx-build -b html -E -c docs/etc "$dir" "$_output" + if [[ ! -f "$dir/conf.py" ]] ; then + cp "etc/conf.py" "$dir/conf.py" + _title=$(cd $dir; python -c "$_get_title_script") + echo "latex_documents = [('index', '$_name.tex', '$_title', 'OPNFV', 'manual'),]" >> "$dir/conf.py" + fi - #sphinx-build -b latex -E -c docs/etc -D project=$_name "$dir" "$_build" - #make -C "$_build" LATEXOPTS='--interaction=nonstopmode' all-pdf - #mv "$_build"/*.pdf "$_output" + mkdir -p "$_output" + + sphinx-build -b html -E "$dir" "$_output" + + # Note: PDF creation may fail in project doc builds. + # We allow this test to be marked as succeeded with + # failure in PDF creation, but leave message to fix it. + # Any failure has to be fixed before B release. + { + sphinx-build -b latex -E "$dir" "$_build" + make -C "$_build" LATEXOPTS='--interaction=nonstopmode' all-pdf + mv "$_build"/*.pdf "$_output" + } || { + _msg="Error: PDF creation for $dir has failed, please fix source rst file(s)." + echo + echo "$_msg" + echo + echo "$_msg" >> gerrit_comment.txt + } done -#TODO(r-mibu): change this to publisher - builder: name: upload-under-review-docs-to-opnfv-artifacts builders: @@ -214,16 +237,10 @@ "gs://$gs_path"/**.html fi - files=$(find docs/output | grep -e 'index.html$' -e 'pdf$' | \ - sed -e "s|^docs/output| http://$gs_path|") - gerrit_comment="Document link(s): - $files" - echo - echo "$gerrit_comment" - echo - ssh -p 29418 gerrit.opnfv.org "gerrit review -p $GERRIT_PROJECT -m '$gerrit_comment' $GERRIT_PATCHSET_REVISION" + echo "Document link(s):" >> gerrit_comment.txt + find docs/output | grep -e 'index.html$' -e 'pdf$' | \ + sed -e "s|^docs/output| http://$gs_path|" >> gerrit_comment.txt -#TODO(r-mibu): change this to publisher - builder: name: upload-merged-docs-to-opnfv-artifacts builders: @@ -255,16 +272,28 @@ "gs://$gs_path"/**.html fi - files=$(find docs/output | grep -e 'index.html$' -e 'pdf$' | \ - sed -e "s|^docs/output| http://$gs_path|") - gerrit_comment="Document link(s): - $files" - echo - echo "$gerrit_comment" - echo - ssh -p 29418 gerrit.opnfv.org "gerrit review -p $GERRIT_PROJECT -m '$gerrit_comment' $GERRIT_PATCHSET_REVISION" + echo "Document link(s):" >> gerrit_comment.txt + find docs/output | grep -e 'index.html$' -e 'pdf$' | \ + sed -e "s|^docs/output| http://$gs_path|" >> gerrit_comment.txt + +- builder: + name: report-docs-build-result-to-gerrit + builders: + - shell: | + #!/bin/bash -e + export PATH=$PATH:/usr/local/bin/ + if [[ -e gerrit_comment.txt ]] ; then + echo + echo "posting review comment to gerrit..." + echo + cat gerrit_comment.txt + echo + ssh -p 29418 gerrit.opnfv.org \ + "gerrit review -p $GERRIT_PROJECT \ + -m '$(cat gerrit_comment.txt)' \ + $GERRIT_PATCHSET_REVISION" + fi -#TODO(r-mibu): change this to publisher - builder: name: remove-old-docs-from-opnfv-artifacts builders: @@ -281,3 +310,18 @@ echo "Deleting Out-of-dated Documents..." gsutil -m rm -r "gs://$gs_path" fi + +- builder: + name: upload-review-docs + builders: + - build-html-and-pdf-docs-output + - upload-under-review-docs-to-opnfv-artifacts + - report-docs-build-result-to-gerrit + +- builder: + name: upload-merged-docs + builders: + - build-html-and-pdf-docs-output + - upload-merged-docs-to-opnfv-artifacts + - report-docs-build-result-to-gerrit + - remove-old-docs-from-opnfv-artifacts |