Docs: Add toctree shortcode docs and render option in the Python script

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>

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("___")