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

…pt (#406)

* 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

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