improve config

A developer was asked to copy all contents in the base config file in
order to set all parameters properly, even if the change is partial.

This patch improves this config by setting all default parameters based
on users' custom config file, so that they can write parameters just
which they want to change.

Change-Id: Ide459c8e9f416b29b114a4bf2a432e8eae1f841e
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 33261ef..85133ad 100644 (file)
--- a/docs/how-to-use-docs/documentation-example.rst
+++ b/docs/how-to-use-docs/documentation-example.rst
@@ -126,10 +126,10 @@ added if they are not set in the ``conf.py``.
   'sphinx.ext.viewcode',
   'sphinx.ext.napoleon']
 * **needs_sphinx** = '1.3'
+* **numfig** = True
 * **master_doc** = 'index'
 * **pygments_style** = 'sphinx'
 * **html_use_index** = False
-* **numfig** = True
 * **html_logo** = 'opnfv-logo.png'
 * **latex_domain_indices** = False
 * **latex_logo** = 'opnfv-logo.png'
@@ -140,8 +140,7 @@ added if they are not set in the ``conf.py``.
 * **version** = '``git last tag name`` (``git last commit hash``)'
 * **project** = '``git repo name``'
 * **copyright** = '``year``, OPNFV'
-
-See http://sphinx-doc.org/config.html to learn sphinx configuration.
+* **rst_epilog** = '    Revision:``git last commit hash``\n    Build date:``build date in year-month-date format``'
 
 **Note:**
 You can leave the file path for OPNFV logo image which will be prepared

diff --git a/etc/conf.py b/etc/conf.py
deleted file mode 100644 (file)
index c4cbae7..0000000
--- a/etc/conf.py
+++ /dev/null
@@ -1,40 +0,0 @@
-# SPDX-license-identifier: Apache-2.0
-##############################################################################
-# Copyright (c) 2016 Linux Foundation and others.
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Apache License, Version 2.0
-# which accompanies this distribution, and is available at
-# http://www.apache.org/licenses/LICENSE-2.0
-##############################################################################
-'''
-Base configuration file for building OPNFV docs
-
-You can override this configuration by putting 'conf.py' in the document
-directory (e.g. docs/how-to-use-docs/conf.py). If there is no 'conf.py'
-in the document directory, this file will be copied to that directory
-before the document builder jobs ('opnfv-docs-verify' and 'opnfv-docs-merge').
-
-You may need python package installation for new sphinx extension.
-Install python package with 'pip' in your machine and add the extension to
-the 'extensions' list below to test the documentation build locally.
-If you feel that your extensions would be useful for other projects too,
-we encourage you to propose a change in the releng repository.
-
-For further guidance see the https://wiki.opnfv.org/documentation/tools page.
-'''
-
-extensions = ['sphinxcontrib.httpdomain',
-              'sphinx.ext.autodoc',
-              'sphinx.ext.viewcode',
-              'sphinx.ext.napoleon']
-
-needs_sphinx = '1.3'
-master_doc = 'index'
-pygments_style = 'sphinx'
-
-html_use_index = False
-numfig = True
-html_logo = 'opnfv-logo.png'
-
-latex_domain_indices = False
-latex_logo = 'opnfv-logo.png'

diff --git a/scripts/docs-build.sh b/scripts/docs-build.sh
index 1c85bad..f95dd48 100755 (executable)
--- a/scripts/docs-build.sh
+++ b/scripts/docs-build.sh
@@ -43,8 +43,8 @@ rev_full="$(git rev-parse HEAD)"
 version="$(git describe --abbrev=0 2> /dev/null || echo draft) ($revision)"
 project="$(basename $(git rev-parse --show-toplevel))"
 html_notes="    Revision: $rev_full\n    Build date: $(date -u +'%Y-%m-%d')"
-default_conf="$OPNFVDOCS_DIR/etc/conf.py"
 opnfv_logo="$OPNFVDOCS_DIR/etc/opnfv-logo.png"
+copyright="$(date +%Y), OPNFV"
 
 function check_rst_doc() {
     _src="$1"
@@ -71,7 +71,7 @@ function add_html_notes() {
             # TODO: remove this, once old templates were removed from all repos.
             echo
             echo "Warn: '_sha1_' was found in [$file], use the latest document template."
-            echo "      See https://wiki.opnfv.org/documentation/tools ."
+            echo "      See http://artifacts.opnfv.org/opnfvdocs/docs/how-to-use-docs ."
             echo
             sed -i "s/ _sha1_/ $git_sha1/g" "$file"
         fi
@@ -98,6 +98,48 @@ function add_config() {
     fi
 }
 
+# Note: User can customize config for specific document by creating 'conf.py'
+#       in the taeget document dir (e.g. docs/abc/conf.py). This config file does
+#       not need to cover all config parameter, as all missing parameter will be
+#       automatically filled by this function.
+function prepare_config() {
+    _src="$1"
+    _name="$2"
+    _conf="$_src/conf.py"
+
+    # default params
+    # Note: If you want to add a new sphinx extention here, you may need python
+    #       package for it (e.g. python package 'sphinxcontrib-httpdomain' is
+    #       required by 'sphinxcontrib.httpdomain'). If you need such python
+    #       package, add the name of the python package into the requirement
+    #       list 'docs/etc/requirements.txt' .
+    add_config "$_conf" 'extensions' \
+    "['sphinxcontrib.httpdomain', 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon']"
+    add_config "$_conf" 'needs_sphinx' "'1.3'"
+    add_config "$_conf" 'numfig' "True"
+    add_config "$_conf" 'master_doc' "'index'"
+    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'"
+
+    # 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" 'copyright' "u'$copyright'"
+    add_config "$_conf" 'rst_epilog' "u'$html_notes'"
+
+    echo "sphinx config to be used:"
+    echo
+    sed -e "s/^/    /" "$_conf"
+    echo
+}
+
 function is_top_dir() {
     [[ "$1" == "$DOCS_DIR" ]]
 }
@@ -131,7 +173,8 @@ function generate_name() {
 check_rst_doc $DOCS_DIR
 
 if [[ ! -d "$OPNFVDOCS_DIR" ]] ; then
-    echo "Error: $OPNFVDOCS_DIR dir not found. See https://wiki.opnfv.org/documentation/tools ."
+    echo "Error: $OPNFVDOCS_DIR dir not found."
+    echo "See http://artifacts.opnfv.org/opnfvdocs/docs/how-to-use-docs ."
     exit 1
 fi
 
@@ -156,7 +199,6 @@ do
     fi
     build="$BUILD_DIR/$name"
     output="$OUTPUT_DIR/$name"
-    conf="$src/conf.py"
 
     echo
     echo "#################${dir//?/#}"
@@ -164,14 +206,7 @@ do
     echo "#################${dir//?/#}"
     echo
 
-    [[ ! -f "$conf" ]] && cp "$default_conf" "$conf"
-    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" 'copyright' "u'$(date +%Y), OPNFV'"
+    prepare_config "$src" "$name"
     cp -f $opnfv_logo "$src/opnfv-logo.png"
 
     mkdir -p "$output"