diff options
| -rw-r--r-- | docs/how-to-use-docs/documentation-example.rst | 51 | ||||
| -rwxr-xr-x | scripts/docs-build.sh | 64 |
2 files changed, 8 insertions, 107 deletions
diff --git a/docs/how-to-use-docs/documentation-example.rst b/docs/how-to-use-docs/documentation-example.rst index 80876e101..16609e068 100644 --- 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). -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 : @@ -82,28 +82,9 @@ Writing RST Markdown 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 -('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 @@ -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' -* **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``' @@ -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. -**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 ========== @@ -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 -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 @@ -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. -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 ---------- diff --git a/scripts/docs-build.sh b/scripts/docs-build.sh index f3fd68980..ebd3c65aa 100755 --- 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:-} -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)" @@ -127,17 +107,12 @@ function prepare_config() { add_config "$_conf" 'html_use_index' "False" add_config "$_conf" 'html_last_updated_fmt' "'%b %d, %Y'" 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 - 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'" @@ -246,45 +221,6 @@ do 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 |