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