generate SwaggerUI docs for models

Author: mathiasertl

.github/workflows/docs.yml

@@ -6,6 +6,7 @@ on:
 env:
   UV_PYTHON_PREFERENCE: only-system
   UV_NO_SYNC: 1
+  SWAGGER_UI_RELEASE: "5.30.3"
 
 jobs:
   run:
@@ -28,7 +29,17 @@ jobs:
         run: uv sync
       - name: doc8 style checks
         run: uv run doc8 docs/
-      - name: Generate documentation
-        run: uv run make -C docs html
+
+      # 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/
+      - 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

.gitignore

@@ -12,6 +12,8 @@ tests/data/docs/_build/
 
 # Documentation
 /docs/_build/
+/docs/_static/swagger-ui/
+/*.tar.gz
 
 # Coverage
 /.coverage

docs/_static/.gitkeep

@@ -37,4 +37,4 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 # html_theme = "alabaster"
-# html_static_path = ["_static"]
+html_static_path = ["_static"]

docs/conf.py

@@ -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:
+

docs/dev.rst

@@ -18,4 +18,5 @@ documentation for details.
    /quickstart
    /how-tos
    /reference
+   /dev
 

docs/index.rst

@@ -2,124 +2,15 @@
 Reference
 #########
 
-Each tutorial file can contain two elements:
+For a complete model reference, please see the `Swagger UI documentation <_static/swagger-ui/index.html>`_.
 
-parts (required, type: :ref:`Parts <reference_parts>`)
-    The individual parts of the tutorial. See :ref:`Parts <reference_parts>` for more information.
-configuration (optional, type: :ref:`Parts <reference_configuration>`)
-    Global/initial configuration for the tutorial. See :ref:`Configuration <reference_configuration>` for
-    more information.
+For a quick overview, each tutorial file can contain two elements:
 
-.. _reference_parts:
+parts (required)
+    The individual parts of the tutorial. A part can have multiple types, either:
 
-*****
-parts
-*****
+    * ``CommandsPartModel`` for a list of commands to execute.
+    * ``FilePartModel`` for a file to create.
 
-Parts is a list of individual "chapters" of your tutorial. For example, a chapter might be a set of commands
-to install a software, or a configuration file that the user is instructed to create.
-
-
-file parts
-==========
-
-File parts are intended to create a file when running a tutorial, and to e.g. instruct the user to create that
-file when rendering the tutorial in documentation. A full example:
-
-.. literalinclude:: /tutorials/file-full-example/tutorial.yaml
-    :language: yaml
-
-The above tutorial will render a file block when rendered:
-
-.. structured-tutorial:: file-full-example/tutorial.yaml
-
-.. structured-tutorial-part::
-
-The configuration options are:
-
-parts[n].contents (optional, str)
-    The contents of the file. Mutually exclusive to ``source``.
-parts[n].source (optional, str)
-    Path of the original file. Mutually exclusive to ``contents``.
-parts[n].destination (optional, str)
-    Where to create the new file.
-parts[n].template (optional, bool)
-    Default: ``True``
-
-    Set to ``False`` if this file should not be rendered as a template. This can be used to copy binary
-    files and cannot be read as text files, or if you want the destination file to be a template.
-parts[n].doc (optional, type: :ref:`parts[n]doc <reference_parts_n_doc>`)
-    See :ref:`parts[n]doc <reference_parts_n_doc>` for details.
-parts[n].run
-    No options are supported thus far.
-
-.. _reference_parts_n_doc:
-
-parts[n].doc
-------------
-
-language (optional, str)
-    Language used for syntax highlighting.
-ignore_spelling (optional, bool)
-    Default: ``False``
-
-    Set to ``True`` to wrap the `caption` option in a ``:spelling:ignore:`` directive for
-    `sphinxcontrib-spelling <https://github.com/sphinx-contrib/spelling>`_.
-
-In addition, any option of the `code-block
-<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block>`_ directive
-are also supported.
-
-commands parts
-==============
-
-.. _reference_configuration:
-
-*************
-configuration
-*************
-
-configuration.doc
-=================
-
-configuration.doc.context (dict)
-    Default: ``{"doc": True, "run": False, "cwd": "~", ...}``
-
-    The initial context for rendering template strings. Additional variables in the context are used to
-    influence the appearance of the prompt in console blocks:
-
-    user
-        Default: ``"user"``
-    host
-        Default: ``"host"``
-    cwd
-        Default: ``"~"``
-    prompt_template
-        Default: ``"{{ user }}@{{ host }}:{{ cwd }}{% if user == 'root' %}#{% else %}${% endif %} "``
-
-configuration.run
-=================
-
-configuration.run.context (dict)
-    Default: ``{"doc": True, "run": False, "cwd": Path.cwd()}``
-
-    The initial context for rendering template strings.
-
-configuration.run.git_export (optional, bool)
-    Default: ``False``
-
-    If set to ``True``, perform a git export before running the tutorial. The current working directory will
-    change to the git export. After the tutorial, the export directory will be removed. This setting
-    overrides ``temporary_directory``.
-
-    If set, the ``cwd`` context variable will point to the temporary directory where the git repository was
-    exported to. The original/initial working directory is available as ``orig_cwd``.
-
-configuration.run.temporary_directory (optional, bool)
-    Default: ``False``
-
-    If set to ``True``, switch to an empty, temporary directory before running the tutorial. The empty
-    directory will be removed once the tutorial is completed.
-
-    If set, the ``cwd`` context variable will point to the temporary directory. The original/initial working
-    directory is available as ``orig_cwd``.
+configuration (optional)
+    Global/initial configuration for the tutorial. This is represented by the ``ConfigurationModel``.

docs/reference.rst

@@ -15,4 +15,4 @@ parts:
   - commands:
       - command: python -m json.tool --compact {{ file_path }}
         doc:
-          output: "{{ file_contents }}"
+          output: "{{ file_contents }}"

docs/tutorials/simple-file/tutorial.yaml

@@ -0,0 +1,70 @@
+"""Script to generate an OpenAPI schema."""
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+import jinja2
+from pydantic import BaseModel
+
+from structured_tutorials.models import TutorialModel
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--swagger-path", type=Path, default=Path.cwd() / "docs" / "_static" / "swagger-ui")
+parser.add_argument(
+    "-o", "--output", action="store_true", default=False, help="Write schema to stdout as well."
+)
+args = parser.parse_args()
+
+swagger_initializer = """window.onload = function() {
+  //<editor-fold desc="Changeable Configuration Block">
+
+  // the following lines will be replaced by docker/configurator, when it runs in a docker-container
+  window.ui = SwaggerUIBundle({
+    spec: {{ spec }},
+    dom_id: '#swagger-ui',
+    deepLinking: true,
+    presets: [
+      SwaggerUIBundle.presets.apis,
+      SwaggerUIStandalonePreset
+    ],
+    plugins: [
+      SwaggerUIBundle.plugins.DownloadUrl
+    ],
+    layout: "StandaloneLayout"
+  });
+
+  //</editor-fold>
+}"""
+
+
+def generate_openapi_schema(
+    model: type[BaseModel], title: str = "Structured Tutorials model reference", version: str = "1.0.0"
+) -> dict[str, Any]:
+    """Generate the OpenAPI schema for the given model."""
+    # Generate Pydantic v2 JSON schema
+    schema = model.model_json_schema(ref_template="#/components/schemas/{model}")
+    schemas = schema.get("$defs", {}).copy()
+    schemas[model.__name__] = schema
+
+    # Minimal OpenAPI 3.0.0 document with only components
+    openapi = {
+        "openapi": "3.0.0",
+        "info": {"title": title, "version": version},
+        "paths": {},  # no API paths
+        "components": {"schemas": schemas},
+    }
+    return openapi
+
+
+openapi = generate_openapi_schema(TutorialModel)
+
+env = jinja2.Environment()
+template = env.from_string(swagger_initializer)
+swagger_js = template.render(spec=json.dumps(openapi, indent=4, sort_keys=True))
+with open(args.swagger_path / "swagger-initializer.js", "w") as fh:
+    fh.write(swagger_js)
+
+if args.output:
+    print(json.dumps(openapi, indent=4, sort_keys=True))