summaryrefslogtreecommitdiffstats
path: root/scripts/docs-build.sh
diff options
context:
space:
mode:
authorRyota MIBU <r-mibu@cq.jp.nec.com>2016-07-20 19:30:05 +0900
committerRyota Mibu <r-mibu@cq.jp.nec.com>2016-07-22 11:50:47 +0000
commita3174cb38b1dc22802da837d1bd0c3e117b9f43a (patch)
tree78073ef4812f3e3a4add81beecb29cf1d6dfe441 /scripts/docs-build.sh
parent2b890ae86bc8dcc16cc7e1f0cb00357c7892486b (diff)
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>
Diffstat (limited to 'scripts/docs-build.sh')
-rwxr-xr-xscripts/docs-build.sh59
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"