render_shortcode_docs.py

#!/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

shortcodes = [
    os.path.join(dirpath, filename)
    for (dirpath, dirs, files) in os.walk(".")
    for filename in sorted(files)
    if (dirpath.endswith("/shortcodes") and filename.endswith(".html"))
]


def shortcode_doc(fn):
    """
    Return description, example, code
    """
    with open(fn) as f:
        data = f.read()

    match = re.match(
        "^{{/\\*.*doc: ([^\n]*)(.*?)^\\*/}}$", data, re.MULTILINE | re.DOTALL
    )

    if not match:
        return None, None, None

    description, code = match.group(1), match.group(2).strip()

    example = (
        code.replace("{{< ", "{{</* ")
        .replace(" >}}", " */>}}")
        .replace("\n>}}", "\n*/>}}")
        .replace("{{% ", "{{%/* ")
        .replace(" %}}", " */%}}")
        .replace("\n%}}", "\n*/%}}")
    )

    # 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


print(
    """\
---
title: Shortcodes
shortcutDepth: 1
---

<!-- DO NOT EDIT.  This file is generated by `tools/render_shortcode_docs.py`.  -->

Markdown is a convenient and simple format to write in.
However, it doesn't always do everything we want (or do it in a nice way).
Rather than adding raw HTML to our source files, Hugo allows us to use
_shortcodes_.  Shortcodes are small snippets that look like this
```
{{</* _shortcodename parameters_ */>}}
```
that Hugo renders using a predefined template.

Here are some shortcodes used by this theme.
"""
)

for shortcode_fn in shortcodes:
    title = os.path.basename(shortcode_fn).replace(".html", "")
    description, example, code = shortcode_doc(shortcode_fn)
    if description is None:
        continue
    print(f"## `{title}`")
    print()
    print(description)
    # We use an extra backtick here so code blocks embedded in the
    # examples work correctly.
    print(f"````\n{example}\n````")

    if code:
        print("This example renders as:")
        print("___")
        print(code)
        print("___")