Recipe Grid Sphinx Extension

A Sphinx extension for embedding compiled recipes in HTML outputs.

This extension is enabled by adding "recipe_grid.sphinx_ext" to your Sphinx extensions list.

This extension adds a recipe directive which may be used to insert recipe grid tables into (HTML-only) sphinx documentation. For example:

.. recipe::
    1 can of spam, sliced
    1 egg, boiled

    fried spam and eggs = fry(spam, egg)

Produces the following output:

fried spam and eggs
1 can of spam sliced fry
1 egg boiled

Referencing earlier recipes

Recipes may be defined across several blocks with later blocks referencing outputs from earlier blocks. For example:

.. recipe::
    serve(
        fried spam and eggs,
        more spam,
    )
fried spam and eggs serve
more spam

Starting a new recipe

A new, independent recipe may be started by adding the :start-new-recipe: option enabling ingredient/output names to be reused without referring to earlier recipes. For example:

.. recipe::
    :start-new-recipe:

    1 egg, scrambled
1 egg scrambled

Scaling

Recipes can be scaled using the :scale: option:

.. recipe::
    :scale: 3/2

    1 packet of cupcake batter
    bake(
        pre-heat oven,
        put into {4} cupcake cases(cupcake batter)
    )
pre-heat oven bake
1 1⁄2 packet of cupcake batter put into 6 cupcake cases

Warning

The :scale: option only scales the recipe shown for the given recipe directive. Where a recipe is given in several blocks, the :scale: option must be repeated otherwise the displayed values will be inconsistent.

Showing sources

To facilitate writing of documentation examples for the recipe grid syntax, the :show-source: option may be used which will cause the rendered recipe grid table to be shown adjacent to the recipe grid source which defines it. For example:

.. recipe::
    :show-source:

    1 oven pizza
    slice(
        bake(
            pre-heat oven,
            oven pizza,
        )
    )

Will be rendered as:

1 oven pizza
slice(
    bake(
        pre-heat oven,
        oven pizza,
    )
)
pre-heat oven bake slice
1 oven pizza

Internals

This Sphinx extension runs as follows:

  1. The builder-inited Sphinx event is used to add the recipe grid CSS to the site.

  2. For each page in the documentation, recipes are compiled as follows:

    1. recipe directives turn into pending_recipe_node nodes and capture the recipe grid source in env.recipe_sources (see RecipeDirective.run()).

    2. In the doctree-read Sphinx event (called after each page has been read and the directives expanded) compiles the recipes into recipe grid abstract recipe descriptions (see :py:mod`recipe_grid.recipe`) and stores these in the pending_recipe_node objects.

  3. During HTML rendering, pending_recipe_node nodes are replaced with rendered recipe tables.