#!/bin/bash # SPDX-license-identifier: Apache-2.0 ############################################################################## # Copyright (c) 2016 NEC 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 ############################################################################## set +e DOCS_DIR=${DOCS_DIR:-docs} INDEX_RST=${INDEX_RST:-index.rst} BUILD_DIR=${BUILD_DIR:-docs_build} OUTPUT_DIR=${OUTPUT_DIR:-docs_output} SRC_DIR=${SRC_DIR:-$BUILD_DIR/_src} VENV_DIR=${VENV_DIR:-$BUILD_DIR/_venv} OPNFVDOCS_DIR=${OPNFVDOCS_DIR:-$BUILD_DIR/_opnfvdocs} GERRIT_COMMENT=${GERRIT_COMMENT:-} revision="$(git rev-parse --short HEAD)" rev_full="$(git rev-parse HEAD)" version="$(git tag | tail -1)" project="$(basename $(git rev-parse --show-toplevel))" html_notes=" Revision: $rev_full\n Build date: $(date -u +'%Y-%m-%d')" opnfv_logo="$OPNFVDOCS_DIR/etc/opnfv-logo.png" copyright="$(date +%Y), OPNFV." copyrightlong="$(date +%Y), OPNFV. Licensed under CC BY 4.0." error_count=0 function set_error() { # TODO(yujunz) log detail errors error_count=$((error_count + 1)) } if [ "$(uname)" == "Darwin" ]; then # Override system $SED/$FIND with gnu $SED and gnu $FIND # If not found, install with # $ brew install gnu-sed findutils echo "macOS detected." SED="gsed" FIND="gfind" else SED="sed" FIND="find" fi function check_rst_doc() { _src="$1" # Note: This check may fail in many jobs for building project docs, since # the old sample has lines more than 120. We ignore failures on this # check right now, but these have to be fixed before OPNFV B release. _out=$(doc8 --max-line-length 240 --ignore D000 "$_src") || { _msg='Warning: rst validation (doc8) has failed, please fix the following error(s).' _errs=$(echo "$_out" | $SED -n -e "/^$_src/s/^/ /p") echo echo -e "$_msg\n$_errs" echo if [ -n "$GERRIT_COMMENT" ]; then echo -e "$_msg\n$_errs" >> "$GERRIT_COMMENT" fi } } function add_html_notes() { _src="$1" $FIND "$_src" -name '*.rst' | while read file do if grep -q -e ' _sha1_' "$file" ; then # 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 http://artifacts.opnfv.org/opnfvdocs/docs/how-to-use-docs ." echo $SED -i "s/ _sha1_/ $git_sha1/g" "$file" fi $SED -i -e "\$a\\\n..\n$html_notes" "$file" done } function prepare_src_files() { mkdir -p "$(dirname $SRC_DIR)" if [ -e "$SRC_DIR" ]; then rm -rf "$SRC_DIR" fi cp -r "$DOCS_DIR" "$SRC_DIR" add_html_notes "$SRC_DIR" } function add_config() { _conf="$1" _param="$2" _val="$3" if ! grep -q -e "^$_param = " "$_conf" ; then echo "Adding '$_param' into $_conf ..." echo "$_param = $_val" >> "$_conf" 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" touch "$_conf" # 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_last_updated_fmt' "'%b %d, %Y'" add_config "$_conf" 'html_logo' "'opnfv-logo.png'" add_config "$_conf" 'html_sidebars' \