workflows: added workflow to facilitate embedding REST-OpenAPI docume…

docs/.gitignore

@@ -16,6 +16,9 @@
 # Build outputs
 _build
 
+# OpenAPI documentation Artifacts
+reference/api/
+
 # Node.js
 package*.json
 

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
@@ -45,7 +45,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 \
-		update
+		fetch-openapi-docs update
 
 full-help: $(VENVDIR)
 	@. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@@ -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 || \

docs/reference/index.md

@@ -24,7 +24,7 @@ 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.
+* <a href="api/redoc-static.html">Snapd REST API</a>: 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.
 
 YAML schemas define exactly what a device, kernel and snap is capable of.