summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRyota MIBU <r-mibu@cq.jp.nec.com>2015-11-25 22:23:01 +0900
committerRyota Mibu <r-mibu@cq.jp.nec.com>2015-11-26 10:23:47 +0000
commit6686b5bfe483b6a518a984b594bb18f9b4239683 (patch)
tree8880cb319eff4022c1e8b37ac12243fbbd1323ef
parent4cb2f7999b7d6bb42443cf32b514f18fc7b579cf (diff)
doc: fix rst and jjb to have consistent view in html and pdf
JIRA: RELENG-16 Change-Id: I6e36f16be6e1c9160820d137a78ac1e7674153f0 Signed-off-by: Ryota MIBU <r-mibu@cq.jp.nec.com>
-rw-r--r--docs/etc/conf.py30
-rw-r--r--docs/how-to-use-docs/documentation-example.rst20
-rw-r--r--docs/how-to-use-docs/index.rst19
-rw-r--r--docs/jenkins-job-builder/index.rst13
-rw-r--r--docs/jenkins-job-builder/opnfv-jjb-usage.rst5
-rw-r--r--jjb/opnfv/opnfv-docs.yml7
-rw-r--r--jjb/releng-macros.yaml104
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