From 00c1e3166d568a47b1c8f4983e5358c611707371 Mon Sep 17 00:00:00 2001
From: Didier Roche <didier.roche@canonical.com>
Date: Thu, 16 Nov 2023 07:58:09 +0100
Subject: [PATCH 1/2] 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.

Co-authored-by: Jean-Baptiste Lallement <jean-baptiste@ubuntu.com>
---
 docs/custom_conf.py  |  7 ++++++
 docs/make_toctree.sh | 54 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100755 docs/make_toctree.sh

diff --git a/docs/custom_conf.py b/docs/custom_conf.py
index 4f947aa4d..5d2d88ab6 100644
--- a/docs/custom_conf.py
+++ b/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)
diff --git a/docs/make_toctree.sh b/docs/make_toctree.sh
new file mode 100755
index 000000000..a64fdb57f
--- /dev/null
+++ b/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

From 88103ff8b673307d9487c44bf9baefb43f65f8fc Mon Sep 17 00:00:00 2001
From: Didier Roche <didier.roche@canonical.com>
Date: Thu, 16 Nov 2023 07:59:20 +0100
Subject: [PATCH 2/2] Avoid an inifinite refresh loop when saving the
 documentation

With make run, listening to any file changes in the destination
directory, the script generating the index files will rerun everytime,
creating a new event, rerunning the generation and so on.
Exclude then any index files under those known subdirectories.
---
 docs/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/Makefile b/docs/Makefile
index a76d8aab9..b6f4a0a5a 100644
--- a/docs/Makefile
+++ b/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