remove pfd/odt creation

This patch also adds description of html_sidebars in how-to doc.

Change-Id: I904ceca3847a085754aacc8d0d0a388f2606c880
JIRA: DOCS-156
Co-Authored-By: Aric Gardner <agardner@linuxfoundation.org>
Signed-off-by: Ryota MIBU <r-mibu@cq.jp.nec.com>

diff --git a/docs/how-to-use-docs/documentation-example.rst b/docs/how-to-use-docs/documentation-example.rst
index 80876e1..16609e0 100644 (file)
--- a/docs/how-to-use-docs/documentation-example.rst
+++ b/docs/how-to-use-docs/documentation-example.rst
@@ -61,7 +61,7 @@ Source Files
 ============
 
 Document source files have to be written in reStructuredText format (rst).
 ============
 
 Document source files have to be written in reStructuredText format (rst).

-Each file would be build as an html page and a chapter in PDF.
+Each file would be build as an html page.

 
 Here is an example source rst file :
 
 
 Here is an example source rst file :
 


@@ -81,29 +81,10 @@ Writing RST Markdown
 
 See http://sphinx-doc.org/rest.html .
 
 
 See http://sphinx-doc.org/rest.html .
 

-**Hint:**
-Table and its contents won't be adjusted, so you may need to fix your source
-text when your table is truncated in PDF version. Or, you can use 'longtable'
-option that splits your table vertically (by rows) in multiple pages.
-It is useful if you have trouble in rendering table containing many rows.
-
-.. code-block:: bash
-
-    .. table::
-        :class: longtable
-
-        +------------------------+------------+----------+----------+
-        | Header row, column 1   | Header 2   | Header 3 | Header 4 |
-        +========================+============+==========+==========+
-        | body row 1, column 1   | column 2   | column 3 | column 4 |
-        +------------------------+------------+----------+----------+
-        | body row 2             | ...        | ...      |          |
-        +------------------------+------------+----------+----------+
-

 **Hint:**
 You can add dedicated contents by using 'only' directive with build type
 **Hint:**
 You can add dedicated contents by using 'only' directive with build type

-('html' and 'pdf') for OPNFV document. But, this is not encouraged to use
-since this may make different views in HTML and PDF version.
+('html' and 'singlehtml') for OPNFV document. But, this is not encouraged to
+use since this may make different views.

 
 .. code-block:: bash
 
 
 .. code-block:: bash
 


@@ -131,11 +112,9 @@ added if they are not set in the ``conf.py``.
 * **pygments_style** = 'sphinx'
 * **html_use_index** = False
 * **html_logo** = 'opnfv-logo.png'
 * **pygments_style** = 'sphinx'
 * **html_use_index** = False
 * **html_logo** = 'opnfv-logo.png'

-* **latex_domain_indices** = False
-* **latex_logo** = 'opnfv-logo.png'
-* **latex_documents** =
-  [('index', '``document directory name``.tex',
-  '``document title in index.rst``', 'OPNFV', 'manual'),]
+* **html_sidebars** = {'**': ['globaltoc.html',
+  '``path to opnfvdocs dir``/etc/pagemenu.html',
+  'searchbox.html']}

 * **release** = '``git last tag name`` (``git last commit hash``)'
 * **version** = '``git last tag name`` (``git last commit hash``)'
 * **project** = '``git repo name``'
 * **release** = '``git last tag name`` (``git last commit hash``)'
 * **version** = '``git last tag name`` (``git last commit hash``)'
 * **project** = '``git repo name``'


@@ -146,15 +125,6 @@ added if they are not set in the ``conf.py``.
 You can leave the file path for OPNFV logo image which will be prepared
 before each document build.
 
 You can leave the file path for OPNFV logo image which will be prepared
 before each document build.
 

-**Hint:**
-In PDF, figures will be floated to get better view. If you want to avoid such
-automated fixes, just add this option to your conf.py after copying the default
-configuration in to the document directory.
-
-.. code-block:: bash
-
-    latex_elements = {'figure_align': 'H'}
-

 Versioning
 ==========
 
 Versioning
 ==========
 


@@ -212,8 +182,8 @@ Verify Job
 The verify job name is **opnfv-docs-verify**.
 
 When you send document changes to gerrit, jenkins will create your documents
 The verify job name is **opnfv-docs-verify**.
 
 When you send document changes to gerrit, jenkins will create your documents

-in HTML and PDF formats to verify that new document can be built successfully.
-Please check the jenkins log and artifact carefully.
+in HTML formats (normal and single-page) to verify that new document can be
+built successfully. Please check the jenkins log and artifact carefully.

 You can improve your document even though if the build job succeeded.
 
 Documents will be uploaded to
 You can improve your document even though if the build job succeeded.
 
 Documents will be uploaded to


@@ -223,11 +193,6 @@ patch set to gerrit, and deleted after the change is merged.
 Document link(s) can be found in your change page on gerrit as a review
 comment.
 
 Document link(s) can be found in your change page on gerrit as a review
 comment.
 

-Note:
-Currently, the job reports 'SUCCESS' as result of document build even if the
-PDF creation failed. This is a provisional workaround, since many projects are
-not ready for PDF creation yet.
-

 Merge Job
 ----------
 
 Merge Job
 ----------
 

diff --git a/scripts/docs-build.sh b/scripts/docs-build.sh
index b6bb5d5..3b1e7b2 100755 (executable)
--- a/scripts/docs-build.sh
+++ b/scripts/docs-build.sh
@@ -17,26 +17,6 @@ VENV_DIR=${VENV_DIR:-$BUILD_DIR/_venv}
 OPNFVDOCS_DIR=${OPNFVDOCS_DIR:-$BUILD_DIR/_opnfvdocs}
 GERRIT_COMMENT=${GERRIT_COMMENT:-}
 
 OPNFVDOCS_DIR=${OPNFVDOCS_DIR:-$BUILD_DIR/_opnfvdocs}
 GERRIT_COMMENT=${GERRIT_COMMENT:-}
 

-get_title_script="
-import os
-from docutils import core, nodes
-
-try:
-    with open('index.rst', 'r') as file:
-        data = file.read()
-    doctree = core.publish_doctree(data,
-        settings_overrides={'report_level': 5,
-                            'halt_level': 5})
-    if isinstance(doctree[0], nodes.title):
-        title = doctree[0]
-    else:
-        for c in doctree.children:
-            if isinstance(c, nodes.section):
-                title = c[0]
-                break
-    print title.astext()
-except:
-    print 'None'"

 revision="$(git rev-parse --short HEAD)"
 rev_full="$(git rev-parse HEAD)"
 version="$(git describe --abbrev=0 2> /dev/null || echo draft) ($revision)"
 revision="$(git rev-parse --short HEAD)"
 rev_full="$(git rev-parse HEAD)"
 version="$(git describe --abbrev=0 2> /dev/null || echo draft) ($revision)"


@@ -126,17 +106,12 @@ function prepare_config() {
     add_config "$_conf" 'pygments_style' "'sphinx'"
     add_config "$_conf" 'html_use_index' "False"
     add_config "$_conf" 'html_logo' "'opnfv-logo.png'"
     add_config "$_conf" 'pygments_style' "'sphinx'"
     add_config "$_conf" 'html_use_index' "False"
     add_config "$_conf" 'html_logo' "'opnfv-logo.png'"

-    add_config "$_conf" 'latex_domain_indices' "False"
-    add_config "$_conf" 'latex_logo' "'opnfv-logo.png'"

     add_config "$_conf" 'html_sidebars' \
                         "{'**': ['globaltoc.html',
                                  '$(cd $OPNFVDOCS_DIR; pwd)/etc/pagemenu.html',
                                  'searchbox.html']}"
 
     # genarated params
     add_config "$_conf" 'html_sidebars' \
                         "{'**': ['globaltoc.html',
                                  '$(cd $OPNFVDOCS_DIR; pwd)/etc/pagemenu.html',
                                  'searchbox.html']}"
 
     # genarated params

-    title=$(cd $_src; python -c "$get_title_script")
-    latex_conf="[('index', '$_name.tex', \"$title\", 'OPNFV', 'manual'),]"
-    add_config "$_conf" 'latex_documents' "$latex_conf"

     add_config "$_conf" 'release' "u'$version'"
     add_config "$_conf" 'version' "u'$version'"
     add_config "$_conf" 'project' "u'$project'"
     add_config "$_conf" 'release' "u'$version'"
     add_config "$_conf" 'version' "u'$version'"
     add_config "$_conf" 'project' "u'$project'"


@@ -238,45 +213,6 @@ do
         fi
     }
 
         fi
     }
 

-    # Note: PDF creation may fail in project doc builds.
-    #       We allow this build job to be marked as succeeded with
-    #       failure in PDF creation, but leave message to fix it.
-    #       Any failure has to be fixed before OPNFV B release.
-    {
-        sphinx-build -b latex -t pdf -E "$src" "$build" && \
-            make -C "$build" LATEXOPTS='--interaction=nonstopmode' all-pdf
-    } && {
-        mv "$build/$name.pdf" "$output"
-    } || {
-        msg="Error: PDF creation for $dir has failed, please fix source rst file(s)."
-        echo
-        echo "$msg"
-        echo
-        if [ -n "$GERRIT_COMMENT" ]; then
-            echo "$msg" >> "$GERRIT_COMMENT"
-        fi
-    }
-
-    # TODO: failures in ODT creation should be handled error and
-    #       cause 'exit 1' before OPNFV B release.
-    tex=$(find $build -name '*.tex' | head -1)
-    odt="${tex%.tex}.odt"
-    if [[ -e $tex ]] && which pandoc > /dev/null ; then
-        (
-            cd $(dirname $tex)
-            pandoc $(basename $tex) -o $(basename $odt)
-        ) && {
-            mv $odt $output/
-        }|| {
-            msg="Error: ODT creation for $dir has failed."
-            echo
-            echo "$msg"
-            echo
-        }
-    else
-        echo "Warn: tex file and/or 'pandoc' are not found, skip ODT creation."
-    fi
-

     if is_top_dir "$dir" ; then
         # NOTE: Having top level document (docs/index.rst) is not recommended.
         #       It may cause conflicts with other docs (mostly with HTML
     if is_top_dir "$dir" ; then
         # NOTE: Having top level document (docs/index.rst) is not recommended.
         #       It may cause conflicts with other docs (mostly with HTML