Write a first MVP for generating structured tutorials

Author: mathiasertl

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: Documentation
+on:
+  push:
+  pull_request:
+
+env:
+  UV_PYTHON_PREFERENCE: only-system
+  UV_NO_SYNC: 1
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Acquire sources
+        uses: actions/[email protected]
+        with:
+          fetch-depth: 0
+      - name: Setup Python
+        uses: actions/[email protected]
+        with:
+          python-version: "3.14"
+          architecture: x64
+      - name: Install uv
+        uses: astral-sh/[email protected]
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync
+      - name: doc8 style checks
+        run: uv run doc8 docs/
+      - name: Generate documentation
+        run: uv run make -C docs html
+      - name: Spelling
+        run: uv run make -C docs spelling

.github/workflows/mypy.yml

@@ -0,0 +1,35 @@
+name: type checking
+on:
+  push:
+  pull_request:
+
+env:
+  UV_PYTHON_PREFERENCE: only-system
+  UV_NO_SYNC: 1
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Acquire sources
+        uses: actions/[email protected]
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/[email protected]
+        with:
+          python-version: "3.14"
+          architecture: x64
+
+      - name: Install uv
+        uses: astral-sh/[email protected]
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: run mypy
+        run: uv run mypy .

.github/workflows/quality.yml

@@ -0,0 +1,37 @@
+name: Code quality
+on:
+  push:
+  pull_request:
+
+env:
+  UV_PYTHON_PREFERENCE: only-system
+  UV_NO_SYNC: 1
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Acquire sources
+        uses: actions/[email protected]
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/[email protected]
+        with:
+          python-version: "3.14"
+          architecture: x64
+
+      - name: Install uv
+        uses: astral-sh/[email protected]
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Ruff format
+        run: uv run ruff format --diff
+
+      - name: Ruff check
+        run: uv run ruff check

.github/workflows/tests.yml

@@ -0,0 +1,42 @@
+name: Tests
+on:
+  push:
+  pull_request:
+
+env:
+  UV_PYTHON_PREFERENCE: only-system
+  UV_NO_SYNC: 1
+
+jobs:
+  run:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ ubuntu-latest ]
+        python-version: [ "3.11", "3.12", "3.13", "3.14" ]
+        sphinx-version: [ "7.3", "7.4", "8.1", "8.2" ]
+
+    name: Python ${{ matrix.python-version }}, Sphinx ${{ matrix.sphinx-version }}
+    steps:
+
+      - name: Acquire sources
+        uses: actions/[email protected]
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/[email protected]
+        with:
+          python-version: ${{ matrix.python-version }}
+          architecture: x64
+
+      - name: Install uv
+        uses: astral-sh/[email protected]
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --group Spinx${{ matrix.sphinx-version }}
+
+      - name: Run tests
+        run: uv run pytest -v --cov-report term-missing --durations=20

.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Documentation
+/docs/_build/
+
+# Coverage
+/.coverage
+
+# IntelliJ products (PyCharm)
+.idea/

README.md

@@ -0,0 +1,19 @@
+# structured-tutorials
+
+what we want to do:
+
+* Tutorial as YAML file
+* list of commands shown
+* config files that are written to a destination
+* Alternatives (e.g. Redis vs. RabbitMQ or MariaDB vs. PostgreSQL)
+  * For both commands and config files
+* Execute commands locally
+  * test output
+  * test status code
+  * add cleanup actions
+  * define tests for successful start
+  * define waits (e.g. until port is open, ...)
+* Render documentation
+  * Show demo output
+* Run locally on command line
+* Run in vagrant

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) -W -n $(O)

docs/conf.py

@@ -0,0 +1,40 @@
+"""Standard Sphinx configuration module."""
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+from pathlib import Path
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "structured-tutorials"
+copyright = "2025, Mathias Ertl"
+author = "Mathias Ertl"
+release = "0.1.0"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx_rtd_theme",
+    "sphinxcontrib.spelling",
+    "structured_tutorials.sphinx",
+]
+html_theme = "sphinx_rtd_theme"
+
+DOC_ROOT = Path(__file__).parent
+tutorial_root = DOC_ROOT / "tutorials"
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# Nitpicky mode warns about references wher the target cannot be found.
+nitpicky = True
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+# html_theme = "alabaster"
+# html_static_path = ["_static"]

docs/include/quickstart.rst

@@ -0,0 +1,7 @@
+Configure the tutorial that is being displayed - this will not show any output:
+
+.. structured-tutorial:: quickstart/quickstart.yaml
+
+Render the first part:
+
+.. structured-tutorial-part::

docs/index.rst

@@ -0,0 +1,19 @@
+.. structured-tutorials documentation master file, created by
+   sphinx-quickstart on Sun May 25 11:37:47 2025.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+structured-tutorials documentation
+==================================
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   /quickstart
+