From dd948284bf122446142c0f1309b557722da7c1a4 Mon Sep 17 00:00:00 2001 From: Robert Fudge Date: Mon, 3 Nov 2025 16:31:42 +0100 Subject: [PATCH 1/9] workflows: added workflow to facilitate embedding REST-OpenAPI documentation in ReadTheDocs --- .github/workflows/fetch-openapi-docs.yml | 26 ++++++++++++++++++++++++ docs/conf.py | 2 +- docs/reference/index.md | 1 + 3 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/fetch-openapi-docs.yml diff --git a/.github/workflows/fetch-openapi-docs.yml b/.github/workflows/fetch-openapi-docs.yml new file mode 100644 index 0000000..241d633 --- /dev/null +++ b/.github/workflows/fetch-openapi-docs.yml @@ -0,0 +1,26 @@ +# .github/workflows/fetch-openapi-docs.yml +name: Fetch OpenAPI Docs + +on: + push: + branches: [ main ] + +jobs: + fetch-docs: + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Download OpenAPI HTML + uses: dawidd6/action-download-artifact@v3 + with: + # The repository owner and name + repo: canonical/snapd-rest-openapi + # The name of the artifact to download + name: api-docs + # The local path to download the artifact to + path: docs/_static/api + + # You would then have your regular ReadTheDocs build process here + # which would now include the files from docs/_static/api diff --git a/docs/conf.py b/docs/conf.py index 930e35e..9d135a9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -196,7 +196,7 @@ # Template and asset locations ####################### -#html_static_path = ["_static"] +html_static_path = ["_static", "_static/api"] #templates_path = ["_templates"] diff --git a/docs/reference/index.md b/docs/reference/index.md index 7c91af7..0c5c936 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -26,6 +26,7 @@ Extend snap functionality with API access and customised environments for your a * [Environment variables](/reference/development/environment-variables): Internal values accessible to snapped applications. * [Snapd REST API](/reference/development/rest-api/snapd-rest-api): Provides access to snapd’s state and many of its key functions. * [REST API error codes](/reference/development/rest-api/error-responses): The types of errors returned by the API. +* [OpenAPI Documentation](/_static/api/index.html): Interactive OpenAPI documentation for the Snapd REST API. YAML schemas define exactly what a device, kernel and snap is capable of. - [snap.yaml](/reference/development/yaml-schemas/the-snap-format): The metadata for a snap. From 125e63c832de4c6d8de3e1b3dc180453d869d725 Mon Sep 17 00:00:00 2001 From: Robert Fudge Date: Mon, 3 Nov 2025 16:45:58 +0100 Subject: [PATCH 2/9] fixup! workflows: added workflow to facilitate embedding REST-OpenAPI documentation in ReadTheDocs --- .github/workflows/fetch-openapi-docs.yml | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/.github/workflows/fetch-openapi-docs.yml b/.github/workflows/fetch-openapi-docs.yml index 241d633..002c1ef 100644 --- a/.github/workflows/fetch-openapi-docs.yml +++ b/.github/workflows/fetch-openapi-docs.yml @@ -1,9 +1,11 @@ -# .github/workflows/fetch-openapi-docs.yml -name: Fetch OpenAPI Docs +name: Fetch OpenAPI Docs and Build Documentation on: push: branches: [ main ] + pull_request: + paths: + - 'docs/**' jobs: fetch-docs: @@ -15,12 +17,13 @@ jobs: - name: Download OpenAPI HTML uses: dawidd6/action-download-artifact@v3 with: - # The repository owner and name repo: canonical/snapd-rest-openapi - # The name of the artifact to download name: api-docs - # The local path to download the artifact to path: docs/_static/api - # You would then have your regular ReadTheDocs build process here - # which would now include the files from docs/_static/api + documentation-checks: + needs: fetch-docs + uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main + with: + working-directory: "docs" + fetch-depth: 0 \ No newline at end of file From 80a8bf53f3662661d9f6ea37840b410e3dc2d6cf Mon Sep 17 00:00:00 2001 From: Robert Fudge Date: Mon, 3 Nov 2025 17:07:01 +0100 Subject: [PATCH 3/9] fixup! fixup! workflows: added workflow to facilitate embedding REST-OpenAPI documentation in ReadTheDocs --- .github/workflows/fetch-openapi-docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/fetch-openapi-docs.yml b/.github/workflows/fetch-openapi-docs.yml index 002c1ef..c4e4c74 100644 --- a/.github/workflows/fetch-openapi-docs.yml +++ b/.github/workflows/fetch-openapi-docs.yml @@ -20,6 +20,7 @@ jobs: repo: canonical/snapd-rest-openapi name: api-docs path: docs/_static/api + workflow: "Lint and build" documentation-checks: needs: fetch-docs From e0f0068142d9112d46c95c6756716b83fe27683e Mon Sep 17 00:00:00 2001 From: Robert Fudge Date: Mon, 3 Nov 2025 18:17:29 +0100 Subject: [PATCH 4/9] fixup! fixup! fixup! workflows: added workflow to facilitate embedding REST-OpenAPI documentation in ReadTheDocs --- .github/workflows/fetch-openapi-docs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/fetch-openapi-docs.yml b/.github/workflows/fetch-openapi-docs.yml index c4e4c74..153ff55 100644 --- a/.github/workflows/fetch-openapi-docs.yml +++ b/.github/workflows/fetch-openapi-docs.yml @@ -17,10 +17,11 @@ jobs: - name: Download OpenAPI HTML uses: dawidd6/action-download-artifact@v3 with: + github_token: ${{ secrets.GITHUB_TOKEN }} repo: canonical/snapd-rest-openapi name: api-docs path: docs/_static/api - workflow: "Lint and build" + workflow: "redocly.yaml" documentation-checks: needs: fetch-docs From f30fbda1d545cb7608b0d1c52484b1b4a4855ad3 Mon Sep 17 00:00:00 2001 From: Robert Fudge Date: Wed, 5 Nov 2025 11:14:38 +0100 Subject: [PATCH 5/9] snap-docs: Integrate workflow with Makefile, ensure embedded documentation displays properly --- docs/.gitignore | 4 ++++ docs/Makefile | 23 ++++++++++++++++++----- docs/conf.py | 3 ++- docs/reference/index.md | 3 +-- 4 files changed, 25 insertions(+), 8 deletions(-) diff --git a/docs/.gitignore b/docs/.gitignore index aad78f1..91d7647 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -2,6 +2,7 @@ *env*/ .sphinx/venv/ + # Sphinx .sphinx/warnings.txt .sphinx/.wordlist.dic @@ -16,6 +17,9 @@ # Build outputs _build +# OpenAPI documentation Artifacts +reference/api/ + # Node.js package*.json diff --git a/docs/Makefile b/docs/Makefile index a6553b8..6dd976c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -11,7 +11,7 @@ SOURCEDIR = . BUILDDIR = _build VENVDIR = $(SPHINXDIR)/venv PA11Y = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json -VENV = $(VENVDIR)/bin/activate +VENV = $(VENVDIR)/bin/activate TARGET = * ALLFILES = *.rst **/*.rst METRICSDIR = $(SOURCEDIR)/.sphinx/metrics @@ -44,7 +44,7 @@ help: .PHONY: full-help spellcheck-install pa11y-install install run html \ epub serve clean clean-doc spelling spellcheck linkcheck woke \ - allmetrics pa11y pdf-prep-force pdf-prep pdf vale-install vale \ + allmetrics pa11y pdf-prep-force pdf-prep pdf vale-install vale fetch-openapi-docs \ update full-help: $(VENVDIR) @@ -90,12 +90,15 @@ pa11y-install: install: $(VENVDIR) -run: install - . $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml --host $(SPHINX_HOST) --port $(SPHINX_PORT) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) +run: install fetch-openapi-docs + mkdir -p $(BUILDDIR)/reference/api + . $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml --host $(SPHINX_HOST) --port $(SPHINX_PORT) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) --post-build "mv $(SOURCEDIR)/reference/api/redoc-static.html $(BUILDDIR)/reference/api/redoc-static.html" # Doesn't depend on $(BUILDDIR) to rebuild properly at every run. -html: install +html: install fetch-openapi-docs . $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) +# @mkdir -p $(BUILDDIR)/reference/api +# @mv $(SOURCEDIR)/reference/api/redoc-static.html $(BUILDDIR)/reference/api/redoc-static.html epub: install . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) @@ -109,6 +112,7 @@ clean: clean-doc rm -rf $(SPHINXDIR)/node_modules/ rm -rf $(SPHINXDIR)/styles rm -rf $(VALE_CONFIG) + rm -rf $(SOURCEDIR)/reference/api clean-doc: git clean -fx "$(BUILDDIR)" @@ -155,6 +159,15 @@ vale-spelling: vale-install @. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/spelling.filter' --glob='*.{md,rst}' $(TARGET) @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt +fetch-openapi-docs: $(SOURCEDIR)/reference/api/index.html + +$(SOURCEDIR)/reference/api/index.html: + @mkdir -p $(SOURCEDIR)/reference/api + @echo "Downloading OpenAPI docs from canonical/snapd-rest-openapi..." + @LATEST_RUN_ID=$$(gh run list -R canonical/snapd-rest-openapi --workflow redocly.yaml --limit 1 --json databaseId -q '.[0].databaseId'); \ + gh run download $$LATEST_RUN_ID -R canonical/snapd-rest-openapi -n api-docs -D $(SOURCEDIR)/reference/api + @echo "OpenAPI docs downloaded to $(SOURCEDIR)/reference/api" + pdf-prep: install @for packageName in $(REQPDFPACKS); do (dpkg-query -W -f='$${Status}' $$packageName 2>/dev/null | \ grep -c "ok installed" >/dev/null && echo "Package $$packageName is installed") && continue || \ diff --git a/docs/conf.py b/docs/conf.py index 9d135a9..f8309d8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -196,7 +196,8 @@ # Template and asset locations ####################### -html_static_path = ["_static", "_static/api"] +#html_static_path = ["_static"] +#html_extra_path = ["reference/api"] #templates_path = ["_templates"] diff --git a/docs/reference/index.md b/docs/reference/index.md index 0c5c936..49b7c9c 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -24,9 +24,8 @@ Deepen your understanding of how snaps can run on all kinds of devices, in all k Extend snap functionality with API access and customised environments for your applications and devices. * [Environment variables](/reference/development/environment-variables): Internal values accessible to snapped applications. -* [Snapd REST API](/reference/development/rest-api/snapd-rest-api): Provides access to snapd’s state and many of its key functions. +* Snapd REST API: Interactive OpenAPI documentation for the Snapd REST API. * [REST API error codes](/reference/development/rest-api/error-responses): The types of errors returned by the API. -* [OpenAPI Documentation](/_static/api/index.html): Interactive OpenAPI documentation for the Snapd REST API. YAML schemas define exactly what a device, kernel and snap is capable of. - [snap.yaml](/reference/development/yaml-schemas/the-snap-format): The metadata for a snap. From 98b9354c04f72be387379b04a8ca232d7e3d92e7 Mon Sep 17 00:00:00 2001 From: Robert Fudge Date: Wed, 5 Nov 2025 11:18:55 +0100 Subject: [PATCH 6/9] snap-docs: remove github workflow for fetching, handled by Makefile now --- .github/workflows/fetch-openapi-docs.yml | 31 ------------------------ 1 file changed, 31 deletions(-) delete mode 100644 .github/workflows/fetch-openapi-docs.yml diff --git a/.github/workflows/fetch-openapi-docs.yml b/.github/workflows/fetch-openapi-docs.yml deleted file mode 100644 index 153ff55..0000000 --- a/.github/workflows/fetch-openapi-docs.yml +++ /dev/null @@ -1,31 +0,0 @@ -name: Fetch OpenAPI Docs and Build Documentation - -on: - push: - branches: [ main ] - pull_request: - paths: - - 'docs/**' - -jobs: - fetch-docs: - runs-on: ubuntu-latest - steps: - - name: Check out repository - uses: actions/checkout@v4 - - - name: Download OpenAPI HTML - uses: dawidd6/action-download-artifact@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - repo: canonical/snapd-rest-openapi - name: api-docs - path: docs/_static/api - workflow: "redocly.yaml" - - documentation-checks: - needs: fetch-docs - uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main - with: - working-directory: "docs" - fetch-depth: 0 \ No newline at end of file From aa4f02d2baf95a0446c5d569a886052fe5d7f0a5 Mon Sep 17 00:00:00 2001 From: Robert Fudge Date: Wed, 5 Nov 2025 11:22:19 +0100 Subject: [PATCH 7/9] fixup! snap-docs: remove github workflow for fetching, handled by Makefile now --- .github/pull_request_template.md | 4 ---- docs/conf.py | 1 - 2 files changed, 5 deletions(-) delete mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md deleted file mode 100644 index ebabf94..0000000 --- a/.github/pull_request_template.md +++ /dev/null @@ -1,4 +0,0 @@ -- [ ] Have you updated `CHANGELOG.md` with relevant non-documentation file changes? -- [ ] Have you updated the documentation for this change? - ------ diff --git a/docs/conf.py b/docs/conf.py index f8309d8..930e35e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -197,7 +197,6 @@ ####################### #html_static_path = ["_static"] -#html_extra_path = ["reference/api"] #templates_path = ["_templates"] From f267fa1a96adadf7990b0b15c683bdbbd26a4cff Mon Sep 17 00:00:00 2001 From: Robert Fudge Date: Wed, 5 Nov 2025 11:23:01 +0100 Subject: [PATCH 8/9] fixup! snap-docs: remove github workflow for fetching, handled by Makefile now --- docs/.gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/.gitignore b/docs/.gitignore index 91d7647..7d1d647 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -2,7 +2,6 @@ *env*/ .sphinx/venv/ - # Sphinx .sphinx/warnings.txt .sphinx/.wordlist.dic From 219adc0e86ea8ad205ccdc12d8d57603b737d6bd Mon Sep 17 00:00:00 2001 From: Robert Fudge Date: Wed, 5 Nov 2025 11:23:59 +0100 Subject: [PATCH 9/9] fixup! snap-docs: remove github workflow for fetching, handled by Makefile now --- docs/Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 6dd976c..e40b489 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -44,8 +44,8 @@ help: .PHONY: full-help spellcheck-install pa11y-install install run html \ epub serve clean clean-doc spelling spellcheck linkcheck woke \ - allmetrics pa11y pdf-prep-force pdf-prep pdf vale-install vale fetch-openapi-docs \ - update + allmetrics pa11y pdf-prep-force pdf-prep pdf vale-install vale \ + fetch-openapi-docs update full-help: $(VENVDIR) @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)