[Python Auto Generate API Documentation] Python Auto Generate API Documentation #tags: python, git, bash, make

.custom-hooks pre-commit

#!/bin/bash

set -e

err_report() {
    echo "There was an issue with one of the pre-commit hooks"
    echo ".git/hooks/pre-commit-*"
    echo "Error on line $1"
}
trap 'err_report $LINENO' ERR

for commit_hook in .git/hooks/pre-commit-*; do
  source "$commit_hook"
done

.custom-hooks pre-commit-pydoc

#!/bin/bash

# grab list of file names that have been staged ready for commit
PY_FILES=($(git diff --staged --name-only | grep "\.py$" || true))

# construct list of directories that have changes (there will be duplicates)
PY_DIRS=()
for i in "${PY_FILES[@]}"; do
  PY_DIRS+=("$(echo $i | cut -d '/' -f 1)")
done

# remove duplicates
PY_DIRS=($(echo "${PY_DIRS[*]}" | tr ' ' '\n' | sort | uniq))

# run pydoc for each directory with changes
if [ ${#PY_DIRS[@]} -gt 0 ]; then
  printf '\n********** Documentation Generation **********\n\n'
  for i in "${PY_DIRS[@]}"; do
    pushd "./$i"
    pycco -p -i -d ./docs/api -- ./**/*.py 2>/dev/null || \
      echo "uh-oh, something went wrong with $i"
    popd
  done
else
  printf "\nThere are no python changes that would cause us to run pydoc\n\n"
fi

# pycco -h
#
# -p, --paths           Preserve path structure of original files
# -d, --directory       The output directory that the rendered files should go
# -i, --generate_index  Generate an index.html document with sitemap content
#
# https://realpython.com/blog/python/generating-code-documentation-with-pycco/

Makefile

REPO := $(shell git rev-parse --show-toplevel)
GIT := ".git/hooks"
HOOK := ".custom-hooks"

define copy_base_hooks
	@cp "$(REPO)/$(HOOK)/pre-commit" "$(REPO)/$(GIT)/pre-commit"
endef

define copy_template_hooks
	@cp "$(REPO)/$(HOOK)/pre-commit-pydoc" "$(REPO)/$(GIT)/pre-commit-pydoc"
endef

check_hook_requirements:
	@pycco -h 1>/dev/null 2>&1 || (echo "Looks like you don't have the pycco executable, we need that to auto generate documentation" && exit 1)

clean_hooks:
	-@rm $(REPO)/$(GIT)/pre-commit.sample &> /dev/null || true
	-@rm $(REPO)/$(GIT)/pre-commit &> /dev/null || true
	-@rm $(REPO)/$(GIT)/pre-commit-* &> /dev/null || true

hooks: check_hook_requirements clean_hooks
	$(call copy_base_hooks)
	$(call copy_template_hooks)

# Explanation of clean_precommits syntax:
#
# -       ...allows errors to be ignored (i.e. don't stop further execution steps)
# @       ...stops makefile from printing command that was executed
# &>      ...redirects stdout/stderr to /dev/null (as command can sometimes error)
# || true ...prevents Make from printing 'error ignored'