structured-tutorials 0.1.0__tar.gz

structured_tutorials-0.1.0/.editorconfig

@@ -0,0 +1,17 @@
+[*]
+end_of_line = lf
+trim_trailing_whitespace = true
+charset = utf-8
+
+[*.{py,pyi}]
+indent_style = space
+indent_size = 4
+
+[*.rst]
+insert_final_newline = true
+max_line_length = 110
+ij_wrap_on_typing = true
+
+[*.{yaml,yml}]
+indent_style = space
+indent_size = 2

structured_tutorials-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Documentation
+on:
+  push:
+  pull_request:
+
+env:
+  UV_PYTHON_PREFERENCE: only-system
+  UV_NO_SYNC: 1
+  SWAGGER_UI_RELEASE: "5.30.3"
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Acquire sources
+        uses: actions/checkout@v4.2.2
+        with:
+          fetch-depth: 0
+      - name: Setup Python
+        uses: actions/setup-python@v5.5.0
+        with:
+          python-version: "3.14"
+          architecture: x64
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5.3.1
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync
+      - name: doc8 style checks
+        run: uv run doc8 docs/
+
+      # Generate Swagger UI docs
+      - name: Fetch Swagger UI
+        run: ./fetch_swagger.sh
+      - name: Generate schema
+        run: uv run generate-schema.py
+
+      # Finally, generate Sphinx docs
+      - name: Spelling
+        run: uv run make -C docs spelling
+      - name: Generate documentation
+        run: uv run make -C docs html

structured_tutorials-0.1.0/.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/checkout@v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5.5.0
+        with:
+          python-version: "3.14"
+          architecture: x64
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5.3.1
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: run mypy
+        run: uv run mypy .

structured_tutorials-0.1.0/.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/checkout@v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5.5.0
+        with:
+          python-version: "3.14"
+          architecture: x64
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5.3.1
+        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

structured_tutorials-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,45 @@
+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.10", "3.11", "3.12", "3.13", "3.14" ]
+        sphinx-version: [ "8.1", "8.2" ]
+        exclude:
+          - python-version: "3.10"
+            sphinx-version: "8.2"
+
+    name: Python ${{ matrix.python-version }}, Sphinx ${{ matrix.sphinx-version }}
+    steps:
+
+      - name: Acquire sources
+        uses: actions/checkout@v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5.5.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          architecture: x64
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5.3.1
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --no-default-groups --group=dev --group Sphinx${{ matrix.sphinx-version }}
+
+      - name: Run tests
+        run: uv run pytest -v --cov-report term-missing --durations=20

structured_tutorials-0.1.0/.github/workflows/wheel.yml

@@ -0,0 +1,32 @@
+name: Wheel
+on:
+  push:
+  pull_request:
+
+env:
+  UV_PYTHON_PREFERENCE: only-system
+  UV_NO_SYNC: 1
+
+jobs:
+  build:
+    name: Build wheel
+    runs-on: ubuntu-latest
+    steps:
+      - name: Acquire sources
+        uses: actions/checkout@v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5.5.0
+        with:
+          python-version: "3.14"
+          architecture: x64
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5.3.1
+        with:
+          enable-cache: true
+
+      - name: Build wheel
+        run: uv build

structured_tutorials-0.1.0/.gitignore

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

structured_tutorials-0.1.0/.readthedocs.yaml

@@ -0,0 +1,44 @@
+
+
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    post_checkout:
+      - git fetch --unshallow || true
+      - git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*' || true
+      - git fetch --all --tags || true
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv 0.9.2
+      - asdf global uv 0.9.2
+    install:
+      - uv sync
+    pre_build:
+      - ./fetch_swagger.sh
+      - uv run generate-schema.py
+    build:
+      html:
+        - uv run sphinx-build -T -b html docs/ $READTHEDOCS_OUTPUT/html
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt
+
+
+

structured_tutorials-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mathias Ertl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

structured_tutorials-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: structured-tutorials
+Version: 0.1.0
+Summary: Add your description here
+Project-URL: Homepage, https://structured-tutorials.readthedocs.io/
+Project-URL: Documentation, https://structured-tutorials.readthedocs.io/
+Project-URL: Source, https://github.com/mathiasertl/structured-tutorials
+Project-URL: Issues, https://github.com/mathiasertl/structured-tutorials/issues
+Project-URL: Changelog, https://structured-tutorials.readthedocs.io/en/latest/changelog.html
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pydantic>=2.11.4
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: sphinx-inline-tabs>=2025
+Requires-Dist: sphinx>=8.2.0; python_version >= '3.11'
+Requires-Dist: sphinx~=8.1.0; python_version < '3.11'
+Requires-Dist: termcolor>=3.2.0
+Requires-Dist: typing-extensions>=4.6.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# structured-tutorials
+
+![image](https://github.com/mathiasertl/structured-tutorials/workflows/Tests/badge.svg)
+![image](https://img.shields.io/pypi/v/structured-tutorials.svg)
+![image](https://img.shields.io/pypi/dm/structured-tutorials.svg)
+![image](https://img.shields.io/pypi/pyversions/structured-tutorials.svg)
+![image](https://img.shields.io/github/license/mathiasertl/structured-tutorials)
+
+`structured-tutorials` allows you to write tutorials that can be rendered as documentation and run on your
+system to verify correctness.
+
+With `structured-tutorials` you to specify steps in a configuration file. A Sphinx plugin allows you to
+render those commands in your project documentation. A command-line tool can load the configuration file and
+run it on your local system.
+
+Please see the [official documentation](https://structured-tutorials.readthedocs.io/) for more detailed
+information.
+
+## Installation / Setup
+
+Install `structured-tutorials`:
+
+```
+pip install structured-tutorials
+```
+
+and configure Sphinx:
+
+```python
+extensions = [
+    # ... other extensions
+    "structured_tutorials.sphinx",
+]
+
+# Optional: Root directory for tutorials
+#tutorial_root = DOC_ROOT / "tutorials"
+```
+
+## Your first (trivial) tutorial
+
+To create your first tutorial, create it in `docs/tutorial.yaml` (or elsewhere, if you configured
+`tutorial_root` in `conf.py`):
+
+```yaml
+parts:
+  - commands:
+      - command: structured-tutorial --help
+        doc:
+          output: |
+            usage: structured-tutorial [-h] path
+            ...
+```
+
+### Run the tutorial
+
+Run the tutorial with:
+
+```
+$ structured-tutorial docs/tutorials/quickstart/tutorial.yaml
+usage: structured-tutorial [-h] path
+...
+```
+
+### Render tutorial in Sphinx:
+
+Configure the tutorial that is being displayed - this will not show any output:
+
+```
+.. structured-tutorial:: quickstart/tutorial.yaml
+
+.. structured-tutorial-part::
+```
+
+## TODO
+* Run in vagrant
+
+# License
+
+This project is licensed under the MIT License. See LICENSE file for details.

structured_tutorials-0.1.0/README.md

@@ -0,0 +1,79 @@
+# structured-tutorials
+
+![image](https://github.com/mathiasertl/structured-tutorials/workflows/Tests/badge.svg)
+![image](https://img.shields.io/pypi/v/structured-tutorials.svg)
+![image](https://img.shields.io/pypi/dm/structured-tutorials.svg)
+![image](https://img.shields.io/pypi/pyversions/structured-tutorials.svg)
+![image](https://img.shields.io/github/license/mathiasertl/structured-tutorials)
+
+`structured-tutorials` allows you to write tutorials that can be rendered as documentation and run on your
+system to verify correctness.
+
+With `structured-tutorials` you to specify steps in a configuration file. A Sphinx plugin allows you to
+render those commands in your project documentation. A command-line tool can load the configuration file and
+run it on your local system.
+
+Please see the [official documentation](https://structured-tutorials.readthedocs.io/) for more detailed
+information.
+
+## Installation / Setup
+
+Install `structured-tutorials`:
+
+```
+pip install structured-tutorials
+```
+
+and configure Sphinx:
+
+```python
+extensions = [
+    # ... other extensions
+    "structured_tutorials.sphinx",
+]
+
+# Optional: Root directory for tutorials
+#tutorial_root = DOC_ROOT / "tutorials"
+```
+
+## Your first (trivial) tutorial
+
+To create your first tutorial, create it in `docs/tutorial.yaml` (or elsewhere, if you configured
+`tutorial_root` in `conf.py`):
+
+```yaml
+parts:
+  - commands:
+      - command: structured-tutorial --help
+        doc:
+          output: |
+            usage: structured-tutorial [-h] path
+            ...
+```
+
+### Run the tutorial
+
+Run the tutorial with:
+
+```
+$ structured-tutorial docs/tutorials/quickstart/tutorial.yaml
+usage: structured-tutorial [-h] path
+...
+```
+
+### Render tutorial in Sphinx:
+
+Configure the tutorial that is being displayed - this will not show any output:
+
+```
+.. structured-tutorial:: quickstart/tutorial.yaml
+
+.. structured-tutorial-part::
+```
+
+## TODO
+* Run in vagrant
+
+# License
+
+This project is licensed under the MIT License. See LICENSE file for details.

structured_tutorials-0.1.0/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)

structured_tutorials-0.1.0/docs/changelog.rst

@@ -0,0 +1,9 @@
+#########
+ChangeLog
+#########
+
+***********
+0.1.0 (TBR)
+***********
+
+Initial version.

structured_tutorials-0.1.0/docs/conf.py

@@ -0,0 +1,41 @@
+"""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",
+    "sphinx_inline_tabs",
+]
+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 where 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"]

structured_tutorials-0.1.0/docs/dev.rst

@@ -0,0 +1,19 @@
+###########
+Development
+###########
+
+***************
+Swagger UI docs
+***************
+
+To generate the Swagger UI documentation locally
+
+* Download the `latest release <https://github.com/swagger-api/swagger-ui/releases>`_.
+* Extract the `dist` folder:
+
+  .. code-block:: console
+
+     tar xf v5.30.3.tar.gz -C docs/_static/ --strip=1 swagger-ui-5.30.3/dist/ --transform s/dist/swagger-ui/
+
+* Generate schema:
+