Speky: Specifications in YAML

Write your requirements and functional tests in a textual format to easily version it with Git, then generate a PDF and a static website.

Roadmap

• PDF with all relevant cross references
• Static website
• Differential PDF to see what changed since last version

Generate a PDF

The speky typst package will generate content from language-agnostic data, like YAML.

Install locally

make -C typst

Use from typst

#import "@local/speky:0.0.7": speky

#speky((
  "requirements.yaml",
  "tests.yaml",
  "comments.yaml",
).map(yaml))

Generate a static website

1. Install speky

   uv tool install git+https://github.com/agagniere/speky#master

2. Generate Myst Markdown:

   speky requirements.yaml tests.yaml comments.yaml \
       --output-folder markdown \
       --project-name Toto

3. Generate HTML with sphinx:

   uv tool install sphinx --with furo,sphinx-design,sphinx-copybutton,myst-parser
   sphinx-build -M html markdown sphinx --conf-dir .

4. Open the website in a browser

   open sphinx/html/index.html