Doc tools: automate example production

[Brian Merchant]

Project description

Currently, example production is a manual process. It could be automated.

Essence of idea: have standardized example syntax consisting of: pre-eval-expr and optional expected-expr. Have standard CLI processor (call it nix-example) to "evaluate" such "example format".

nix-example takes two inputs:

• string in "example format"
• zero or more templates (output template: string with at least one slot for pre-eval-expr, expected-expr and post-eval-expr).

nix-example would:

• evaluate pre-eval-expr using nix repl (or any other nix expression evaluator), producing post-eval-expr
• if expected-expr exists, verifies it against post-eval-expr
• return strings corresponding to each provided template filled with *-eval-expr

Benefits:

Fire-and-forget automation for something that is error prone: copying and pasting, manual verification between Nix updates, etc.

Solution is:

• independent of mdBook (yet can be integrated easily with it similar to mdBook's existing playground snippet processor)
• independent of markdown (yet can be integrated easily with it, as it can produce markdown formatted output easily given appropriate template strings)

Wide usage:

• Nix manuals, Nix reference manual, nix.dev

Steps

• Determine/fix/specify "example" syntax
• Create CLI tool nix-example