From 379943b9398d3165b6c52a7edad0401451517ca0 Mon Sep 17 00:00:00 2001 From: Anton Gilgur Date: Sat, 13 Jan 2024 21:55:53 -0500 Subject: [PATCH] docs: update SwaggerUI version - use latest [5.11.0](https://github.com/swagger-api/swagger-ui/releases/tag/v5.11.0) instead of the 2 years outdated [4.5.0](https://github.com/swagger-api/swagger-ui/releases/tag/v4.5.0) - it seems like the version was taken directly from [the SwaggerUI installation docs](https://github.com/swagger-api/swagger-ui/blob/v5.11.0/docs/usage/installation.md#unpkg), which still has an old version listed - in fact, the entire code block was taken from the doc - significantly simplify the code block as it renders inside of existing MD/HTML - a second `DOCTYPE`, `html`, `head`, `body`, etc tags are actually invalid HTML, but either `mkdocs` ignored some of those or browsers just ignore some of those - fixing invalid HTML makes this doc page more robust - also fix the indentation in the code block too, which also did not meet style guidelines - this seems to make it slightly more performant, which is our main issue, but also has other benefits of using a current version of a dep - add a `markdownlint-disable` comment to allow the inline HTML - add a comment describing why it's necessary - similarly add a comment to the PR template explaining why that one is necessary too - remove the `Makefile`'s ignore on `swagger.md` for docs linting et al Signed-off-by: Anton Gilgur --- .github/pull_request_template.md | 11 +++++----- Makefile | 6 +++--- docs/swagger.md | 37 +++++++++++--------------------- 3 files changed, 20 insertions(+), 34 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1a0f687f92ef..7423881af9f9 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,4 +1,4 @@ - + - ### Verification - diff --git a/Makefile b/Makefile index b9f81e6acc42..0f8f5e86766b 100644 --- a/Makefile +++ b/Makefile @@ -684,7 +684,7 @@ endif .PHONY: docs-spellcheck docs-spellcheck: /usr/local/bin/mdspell # check docs for spelling mistakes - mdspell --ignore-numbers --ignore-acronyms --en-us --no-suggestions --report $(shell find docs -name '*.md' -not -name upgrading.md -not -name README.md -not -name fields.md -not -name upgrading.md -not -name swagger.md -not -name executor_swagger.md -not -path '*/cli/*') + mdspell --ignore-numbers --ignore-acronyms --en-us --no-suggestions --report $(shell find docs -name '*.md' -not -name upgrading.md -not -name README.md -not -name fields.md -not -name upgrading.md -not -name executor_swagger.md -not -path '*/cli/*') /usr/local/bin/markdown-link-check: # update this in Nix when upgrading it here @@ -695,7 +695,7 @@ endif .PHONY: docs-linkcheck docs-linkcheck: /usr/local/bin/markdown-link-check # check docs for broken links - markdown-link-check -q -c .mlc_config.json $(shell find docs -name '*.md' -not -name fields.md -not -name swagger.md -not -name executor_swagger.md) + markdown-link-check -q -c .mlc_config.json $(shell find docs -name '*.md' -not -name fields.md -not -name executor_swagger.md) /usr/local/bin/markdownlint: # update this in Nix when upgrading it here @@ -707,7 +707,7 @@ endif .PHONY: docs-lint docs-lint: /usr/local/bin/markdownlint # lint docs - markdownlint docs --fix --ignore docs/fields.md --ignore docs/executor_swagger.md --ignore docs/swagger.md --ignore docs/cli --ignore docs/walk-through/the-structure-of-workflow-specs.md + markdownlint docs --fix --ignore docs/fields.md --ignore docs/executor_swagger.md --ignore docs/cli --ignore docs/walk-through/the-structure-of-workflow-specs.md /usr/local/bin/mkdocs: # update this in Nix when upgrading it here diff --git a/docs/swagger.md b/docs/swagger.md index ee0ae0a718e7..20865b65cbce 100644 --- a/docs/swagger.md +++ b/docs/swagger.md @@ -1,27 +1,14 @@ # API Reference - - - - - - - SwaggerUI - - - -
- - - - + +
+ + +