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>

1 files changed, 47 insertions, 12 deletions

diff --git a/scripts/docs-build.sh b/scripts/docs-build.sh
index 1c85bad79..f95dd481d 100755
--- 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"