From b1dd9bc0e84a8a22f903b6b71c089d14c103caa9 Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Mon, 13 Nov 2023 14:53:13 -0600
Subject: [PATCH] Docs: Add toctree shortcode docs and render option in the
 Python script (#406)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add: (render_shortcode_docs.py) Options processing

This allows each shortcode file to pass a dict of options to this
Python program.

Currently the only one supported is "render", which may be set to
False to disable rendering of the shortcode into the documentation.
This is useful when a shortcode will not render meaningfully into the
documentation file (e.g. the "toctree" shortcode only works when in an
appropriate file hierarchy).

* Docs: Add toctree shortcode documentation

* '[pre-commit.ci 🤖] Apply code format tools to PR'

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 layouts/shortcodes/toctree.html | 10 ++++++++
 tools/render_shortcode_docs.py  | 45 ++++++++++++++++++++++++++++++---
 2 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/layouts/shortcodes/toctree.html b/layouts/shortcodes/toctree.html
index fa10fec9..1de79167 100644
--- a/layouts/shortcodes/toctree.html
+++ b/layouts/shortcodes/toctree.html
@@ -1,3 +1,13 @@
+{{/*
+
+options: {"render": False}
+
+doc: Shows a table-of-contents tree for the Hugo [`Sections`](https://gohugo.io/methods/page/sections/) in the current hierarchy.  In this documentaion, an example of the `toctree` is seen on the [Examples]({{% relref "examples" %}}) page.
+
+{{< toctree >}}
+
+*/}}
+
 <div class="toctree-wrapper">
   {{- range $section := .Page.Sections }}
   <ul>
diff --git a/tools/render_shortcode_docs.py b/tools/render_shortcode_docs.py
index c793d56d..5f8e03a7 100644
--- a/tools/render_shortcode_docs.py
+++ b/tools/render_shortcode_docs.py
@@ -1,3 +1,22 @@
+#!/usr/bin/env python3
+
+# NOTE: In each shortcode's HTML file, options may be provided in the
+# form of a Python dict after "options: " at the beginning of a line
+# inside the specially commented preface.  For example:
+
+# {{/*
+#
+# options: {"render": False}
+#
+# doc: Foo bar.
+#
+# {{< foo bar >}}
+#
+# */}}
+
+# That option (currently the only one) disables rendering of the
+# shortcode in the documentation.
+
 import os
 import re
 
@@ -32,6 +51,22 @@ def shortcode_doc(fn):
         .replace(" %}}", " */%}}")
     )
 
+    # Process rendering options.
+    options_match = re.match(
+        "^{{/\\*.*^options: +({[^\n]+}) *$.*\\*/}}$", data, re.MULTILINE | re.DOTALL
+    )
+    if options_match:
+        # Read Python dict of options.
+        from ast import literal_eval
+
+        options = literal_eval(options_match.group(1))  # Safely read expression.
+        assert isinstance(options, dict)
+
+        if "render" in options:
+            if not options["render"]:
+                # Disable rendering of the example.
+                code = None
+
     return description, example, code
 
 
@@ -68,7 +103,9 @@ def shortcode_doc(fn):
     # We use an extra backtick here so code blocks embedded in the
     # examples work correctly.
     print(f"````\n{example}\n````")
-    print("This example renders as:")
-    print("___")
-    print(code)
-    print("___")
+
+    if code:
+        print("This example renders as:")
+        print("___")
+        print(code)
+        print("___")