1#!/bin/sh
2# Copyright 2019-2023 The Khronos Group Inc.
3#
4# SPDX-License-Identifier: Apache-2.0
5
6# Generate documentation for the python scripts in this repo, using pdoc3:
7# https://pdoc3.github.io/pdoc/
8#
9# Output is under $(OUTDIR)/python-docs
10
11set -e
12
13# Pipe in some paths. We will convert them to module names and document them.
14pathsToDocs() {
15    grep -v "test_" | \
16    grep -v "__init__.py" | \
17    sed -e 's/[.]py//' -e 's:/:.:g' | \
18    xargs --verbose pdoc3 --html --force --output-dir $1
19}
20
21# Main body of script
22(
23    cd $(dirname $0)
24    # Needed to complete the build - cannot import genRef.py without it.
25    make pyapi
26
27    SPECDIR=$(pwd)
28    OUTDIR=$(pwd)/gen/out/python-docs
29    INDEX=$OUTDIR/index.html
30    mkdir -p $OUTDIR
31    cp scripts/__init__.py.docs scripts/__init__.py
32    export PYTHONPATH=${SPECDIR}/scripts
33    (
34        # # scripts under specification
35        cd $SPECDIR/scripts
36        ls *.py
37
38        # Generate the index files
39        # echo "scripts"
40        echo "scripts.spec_tools"
41
42    ) | pathsToDocs $OUTDIR
43
44    # Generate a simple index file, since generating one with pdoc3 chokes on the Retired directory.
45    echo "<html><body><h1>Python modules</h2><ul>" > $INDEX
46    (
47        cd $SPECDIR/scripts
48        ls *.py
49    ) | while read -r fn; do
50        MODNAME=$(echo $fn | sed -r  's/([a-zA-Z_]+)([.]py)?/\1/')
51        if [ -f $OUTDIR/$MODNAME.html ]; then
52            # Only make non-dead links
53            echo "<li><a href=$MODNAME.html>$MODNAME</a></li>" >> $INDEX
54        fi
55    done
56    echo "<li><a href=spec_tools/index.html>spec_tools</a></li>" >> $INDEX
57    echo "</ul></body></html>" >> $INDEX
58
59    # Move index files to a more useful place
60    rm -rf $OUTDIR/spec_tools
61    mv $OUTDIR/scripts/spec_tools $OUTDIR/spec_tools
62    # delete duplicate generated files
63    rm -rf $OUTDIR/scripts
64
65    rm -f scripts/__init__.py
66)
67