build_docs.sh

#!/bin/bash
# This shell script builds the docs for msiempy 
# I've been running it from MacOS but I beleive it's valid on Linux too. 

# It will automatically generate pydoctor documentation coupled with mkdocs to show different versions
# It also adds git reference and tag info

# Will first write the docs under the version's folder, and then overwrites default (lastest in the root folder). 
# See the mkdocs site under ./site folder 
# Then it will copy the content to your storage location: if passed with -o <path>
# The storage should not be deleted and you should use the same storage for all versions. ./site will still contain the genrated site

# The 'index.md' files under './docs/<version>/index.md' should be kept in the repo for mkdocs to ba able to generate the navbar with different versions.

# Requirements: graphviz, pydoctor mkdocs mkdocs-awesome-pages-plugin
# Install python requirements
# python3 setup.py install
# python3 -m pip install -r requirements.txt
# sudo apt-get install graphviz || sudo yum install graphviz || brew install graphviz

# Usage ./build_docs "./mfesiem.github.io/docs/test/msiempy"

# Stop if errors
set -euo pipefail

IFS=$'\n\t,'

usage(){
    echo "[USAGE] $0 [-h] [-o <path>] [-f]" 1>&2
    echo
    echo "This shell script builds the docs for msiempy. Generates the mkdocs site under './site' folder, allows versionning and include a few handy options. Unix only. "
    echo
    echo -e "\t-h\tPrint this help message."
    echo -e "\t-o\t<path>\tStorage location. The content of the mkdocs+pydoctor site will be copied to this folder. './site'  folder will still contain the genrated site. "
    echo -e "\t-f\t\tOverwrite the existing 'index.md' files located in the './docs/<version>' folder. Default behaviour will quit if './docs/<version>/index.md' already exists. "
    echo -e "\t-d\t\tDevelopment mode: do not write under './docs/<version>' but directly to './docs' only. Default behaviour will write to './docs/<version>' "
    echo -e "\t-i\t\tGenerate only the './docs/<version>/index.md' file and exit. "

    exit -1
}

function restore_docs_folder()
{
    # Restore docs folder
    if [[ -d ./docs-tmp ]]; then
        rm -rf ./docs
        cp -r ./docs-tmp ./docs
        rm -rf ./docs-tmp
    fi
}

trap restore_docs_folder EXIT

multi_version_site=""
force=false
devel=false
index_only=false

while getopts ":ho:fdi" arg; do
    case "${arg}" in
        h) #Print help
            usage
            ;;

        o)
            # The out folder # This should be sychronized with alternative storage.  
            multi_version_site=${OPTARG}
            mkdir -p "${multi_version_site}"
            ;;
        f)
            force=true
            ;;
        
        d)
            devel=true
            ;;

        i)
            index_only=true
            ;;

        *)
            echo "[ERROR] Syntax mistake calling the script."
            usage
            exit
            ;;
    esac
done 

# Figure the project version
project_version="$(python3 setup.py -V)"

# Figure commit ref
git_sha="$(git rev-parse HEAD)"
if ! git describe --exact-match --tags; then
    tag="Warning: Not a tagged version."
    is_tag=0
else
    git_sha="$(git describe --exact-match --tags)"
    tag="Tag: ${git_sha}."
    is_tag=1
fi

# Folder i.e. ./docs/0.3.5/
if ! [[ ${devel} = true ]]; then
    docs_folder="./docs/${project_version}"
else
    docs_folder="./docs"
fi

# Create the docs folder if it doesn't exists
if [ -e "${docs_folder}/index.md" ]; then
    if ! [[ ${force} = true ]]; then
        echo "[ERROR] An 'index.md' already exists in ${docs_folder}. Use -f to overwrite. "
        exit 1
    fi
else
    mkdir -p "${docs_folder}"
fi

#Figure out branch
branch=$(git rev-parse --abbrev-ref HEAD)

# Include readme
readme=$(cat ./README.md)

# Autogenerated index
echo "# msiempy ${project_version}

<!-- The mkdocs index to should show msiempy version in the header -->

<!-- This file should not be directly edited, edit the script build_docs.sh instead -->

*This is an autogenerated index for [msiempy](https://github.com/mfesiem/msiempy/) version ${project_version}, git reference [${git_sha}](https://github.com/mfesiem/msiempy/tree/${git_sha})*.  
*${tag}*  
*Generated from branch ${branch}, on the $(date).*    

# Documentation summary

**[View the Python API Reference](msiempy.html)** 

Or navigate: 

- A listing of [all modules and packages](moduleIndex.html), organized by package hierarchy.
- A listing of [all classes](classIndex.html), organized by inheritance hierarchy.
- A listing of [all functions, classes, modules and packages](nameIndex.html), ordered by name.

For more exemples, see the [samples folder](https://github.com/mfesiem/msiempy/tree/master/samples) or
the [tests](https://github.com/mfesiem/msiempy/tree/master/tests) for other scripts. 

See also: 

- [Class diagram](classes.png), ([Packages diagram](packages.png))
- [mfesiem.github.io](https://mfesiem.github.io) (generated PDFs and other links)  

(*Links are relative*)

***

Back to [GitHub | README](https://github.com/mfesiem/msiempy/)

" > "${docs_folder}/index.md"
echo "[INFO] Write docs index to ${docs_folder}/index.md "

if [[ ${index_only} = true ]]; then
    exit 0
fi

# Backup docs folder right after creating index.md. Only index.md should be kept here
if [[ -d ./docs ]]; then
    cp -r docs docs-tmp
fi

# Generate diagrams under the ./docs/version folder

pyreverse -s 1 -f PUB_ONLY -o png -m y msiempy
mv ./classes.png "${docs_folder}"
mv ./packages.png "${docs_folder}"

# Generate 
python3 ./samples/list_request_args.py > "./all_request_args.rst"

# Run pydoctor build, just before the mkdocs build
# The index.html will be overwritten

pydoctor \
    --add-package=msiempy \
    --project-name="msiempy" \
    --html-viewsource-base="https://github.com/mfesiem/msiempy/tree/${git_sha}" \
    --make-html \
    --project-base-dir="$(pwd)" \
    --docformat=restructuredtext \
    --intersphinx=https://docs.python.org/3/objects.inv \
    --html-output="${docs_folder}" || true

# Copy the docs from the versionned folder to the latest (root folder). Only if not already there. 
if ! [ ${docs_folder} = "./docs" ] ; then
    cp -rf ${docs_folder}/* "./docs"
fi

# Run mkdocs build, will overwrite pydoctor index.html files
mkdocs build

# Copy the docs in the versionned folder to the site with multiples versions
if [[ -n "${multi_version_site}" ]]; then
    cp -r ./site/* "${multi_version_site}"
    echo "[INFO] Site content copied to: ${multi_version_site}"
fi

restore_docs_folder