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/.gitignore b/docs/.gitignore index aad78f1..7d1d647 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -16,6 +16,9 @@ # Build outputs _build +# OpenAPI documentation Artifacts +reference/api/ + # Node.js package*.json diff --git a/docs/Makefile b/docs/Makefile index a6553b8..e40b489 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 @@ -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 || \ diff --git a/docs/reference/index.md b/docs/reference/index.md index 7c91af7..49b7c9c 100644 --- a/docs/reference/index.md +++ b/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. +* 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. YAML schemas define exactly what a device, kernel and snap is capable of.