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:
The
builder-inited
Sphinx event is used to add the recipe grid CSS to the site.- For each page in the documentation, recipes are compiled as follows:
recipe
directives turn intopending_recipe_node
nodes and capture the recipe grid source inenv.recipe_sources
(seeRecipeDirective.run()
).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 thepending_recipe_node
objects.
During HTML rendering,
pending_recipe_node
nodes are replaced with rendered recipe tables.