add readthedocs config and project urls

Author: mathiasertl

.github/workflows/docs.yml

@@ -32,9 +32,7 @@ jobs:
 
       # Generate Swagger UI docs
       - name: Fetch Swagger UI
-        run: wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v${SWAGGER_UI_RELEASE}.tar.gz
-      - name: Extract Swagger UI
-        run: tar xf v${SWAGGER_UI_RELEASE}.tar.gz -C docs/_static/ --strip=1 swagger-ui-${SWAGGER_UI_RELEASE}/dist/ --transform s/dist/swagger-ui/
+        run: ./fetch_swagger.sh
       - name: Generate schema
         run: uv run generate-schema.py
 

.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
+
+
+

README.md

@@ -6,13 +6,71 @@
 ![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 Sphinx documentation and also be
-run on your local system to verify correctness.
+`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 commands in a configuration file. A Sphinx plugin allows you to
+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
 

docs/changelog.rst

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

docs/index.rst

@@ -12,11 +12,12 @@ documentation for details.
 
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
    /quickstart
    /how-tos
    /reference
+   /changelog
    /dev
 

fetch_swagger.sh

@@ -0,0 +1,6 @@
+#!/bin/bash -ex
+
+SWAGGER_UI_RELEASE=5.30.3
+
+wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v${SWAGGER_UI_RELEASE}.tar.gz
+tar xf v${SWAGGER_UI_RELEASE}.tar.gz -C docs/_static/ --strip=1 swagger-ui-${SWAGGER_UI_RELEASE}/dist/ --transform s/dist/swagger-ui/

pyproject.toml

@@ -37,6 +37,13 @@ dynamic = ["version"]
 [project.scripts]
 structured-tutorial = "structured_tutorials.cli:main"
 
+[project.urls]
+Homepage = "https://structured-tutorials.readthedocs.io/"
+Documentation = "https://structured-tutorials.readthedocs.io/"
+Source = "https://github.com/mathiasertl/structured-tutorials"
+Issues = "https://github.com/mathiasertl/structured-tutorials/issues"
+Changelog = "https://structured-tutorials.readthedocs.io/en/latest/changelog.html"
+
 [tool.coverage.run]
 source = [
     "structured_tutorials",

tests/test_cli.py

@@ -3,6 +3,7 @@
 
 """Test the cli entry point function."""
 
+from collections.abc import Iterator
 from pathlib import Path
 from unittest.mock import patch
 
@@ -13,10 +14,10 @@
 
 
 @pytest.fixture(autouse=True)
-def mock_setup_logging() -> None:
+def mock_setup_logging() -> Iterator[None]:
     """Fixture to mock logging setup - so that it is not called multiple times."""
-    with patch("structured_tutorials.cli.setup_logging"):
-        return
+    with patch("structured_tutorials.cli.setup_logging", autospec=True):
+        yield
 
 
 def test_simple_tutorial(simple_tutorial: TutorialModel) -> None: