docs: sphinx reference doc index generation (#853)

Run a pre-hook to create index file in policy reference.
To be able to list the whole policy reference definition, we needs index
file for each category.
Create them on the fly, listing the reference policies generated in the
reference destination directory, before generating the finale
documentation.

-----

UDENG-1450

docs/Makefile

@@ -53,7 +53,7 @@ woke-install:
 install: $(VENVDIR) woke-install
 
 run: install
-	. $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	. $(VENV); sphinx-autobuild --re-ignore 'reference/policies/.*/index.md' -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 
 # Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
 html: install

docs/custom_conf.py

@@ -167,3 +167,10 @@
 ############################################################
 
 ## Add any configuration that is not covered by the common conf.py file.
+
+def run_before_build(app):
+    import subprocess
+    subprocess.run(['./make_toctree.sh', 'reference/policies/Computer Policies', 'reference/policies/User Policies'])
+
+def setup(app):
+    app.connect('builder-inited', run_before_build)

docs/make_toctree.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+
+# Generate our toc tree for Computer and User policies to reflect the hierarchy in reference
+# That way, each key have a complete hierarchy folder structure.
+set -eu
+
+# Function to create index.md in a directory
+create_index() {
+    local dir=$1
+    local index_file="$dir/index.md"
+
+    # Get the name of the directory for the title
+    local title=$(basename "$dir")
+
+    cat <<EOF > "${index_file}"
+# $title
+
+\`\`\`{toctree}
+:maxdepth: 99
+
+EOF
+
+    # List directories and files, excluding index.md
+    for item in "$dir"/*; do
+        if [ -d "$item" ]; then
+            # It's a directory, add its index file
+            echo "$(basename "$item")/index" >> "$index_file"
+        elif [ -f "$item" ] && [ "$(basename "$item")" != "index.md" ]; then
+            # It's a file, add it directly to the index
+            echo "$(basename "$item" .md)" >> "$index_file"
+        fi
+    done
+
+    echo '```' >> "$index_file"
+}
+
+# Recursive function to walk through directories
+walk_dirs() {
+    local current_dir=${1%/}
+
+    # Create index in the current directory
+    create_index "$current_dir"
+
+    # Recursively walk into subdirectories
+    for subdir in "$current_dir"/*/; do
+        if [ -d "$subdir" ]; then
+            walk_dirs "$subdir"
+        fi
+    done
+}
+
+for d in "$@"; do
+    walk_dirs "$d"
+done