[Docs] Add link checker for docs (mckinsey#475)

Signed-off-by: Antony Milne <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Jo Stichbury <[email protected]>
kaestro · May 14, 2024 · 2c3e94c · 2c3e94c
1 parent 2805e95
commit 2c3e94c
Show file tree

Hide file tree

Showing 8 changed files with 119 additions and 8 deletions.
diff --git a/vizro-ai/.readthedocs.yaml b/vizro-ai/.readthedocs.yaml
@@ -11,6 +11,6 @@ build:
     python: "3.11"
   commands:
     - pip install hatch
-    - cd vizro-ai/ && hatch run docs:mkdocs build --strict
+    - cd vizro-ai/ && hatch run docs:build && hatch run docs:link-check
     - mkdir --parents $READTHEDOCS_OUTPUT
     - mv vizro-ai/site/ $READTHEDOCS_OUTPUT/html
diff --git a/vizro-ai/changelog.d/20240513_162508_antony.milne_add_link_checker.md b/vizro-ai/changelog.d/20240513_162508_antony.milne_add_link_checker.md
@@ -0,0 +1,48 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Highlights ✨
+
+- A bullet item for the Highlights ✨ category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Removed
+
+- A bullet item for the Removed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Added
+
+- A bullet item for the Added category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Changed
+
+- A bullet item for the Changed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
diff --git a/vizro-ai/hatch.toml b/vizro-ai/hatch.toml
@@ -48,10 +48,18 @@ dependencies = [
   "mkdocs",
   "mkdocs-material",
   "mkdocs-git-revision-date-localized-plugin",
-  "mkdocstrings[python]"
+  "mkdocstrings[python]",
+  "linkchecker"
 ]
 detached = true
-scripts = {serve = "mkdocs serve --strict"}
+
+[envs.docs.scripts]
+build = "mkdocs build --strict"
+# Disable warnings on the linkcheck so that HTTP redirects are accepted. We could ignore only that warning and specify
+# more advanced settings using a linkcheckerrc config file. openai.com doesn't seem to work well with linkchecking,
+# throwing 403 errors, but these are not real errors.
+link-check = "linkchecker site --check-extern --no-warnings --ignore=404.html --ignore-url=127.0.0.1 --ignore-url=https://platform.openai.com/docs/models --ignore-url=openai.com --ignore-url=https://openai.com/"
+serve = "mkdocs serve --strict"
 
 [envs.lint]
 dependencies = [

diff --git a/vizro-core/.readthedocs.yaml b/vizro-core/.readthedocs.yaml
@@ -11,6 +11,6 @@ build:
     python: "3.11"
   commands:
     - pip install hatch
-    - cd vizro-core/ && hatch run docs:mkdocs build --strict
+    - cd vizro-core/ && hatch run docs:build && hatch run docs:link-check
     - mkdir --parents $READTHEDOCS_OUTPUT
     - mv vizro-core/site/ $READTHEDOCS_OUTPUT/html
diff --git a/vizro-core/changelog.d/20240513_162501_antony.milne_add_link_checker.md b/vizro-core/changelog.d/20240513_162501_antony.milne_add_link_checker.md
@@ -0,0 +1,48 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Highlights ✨
+
+- A bullet item for the Highlights ✨ category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Removed
+
+- A bullet item for the Removed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Added
+
+- A bullet item for the Added category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Changed
+
+- A bullet item for the Changed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
diff --git a/vizro-core/docs/index.md b/vizro-core/docs/index.md
@@ -38,7 +38,7 @@ Vizro is a toolkit for creating modular data visualization applications.
     ---
 
     [:octicons-arrow-right-24: How is Vizro different to Streamlit?](pages/explanation/faq/#how-does-vizro-differ-from-dash-or-streamlit) <br/>
-    [:octicons-arrow-right-24: Other FAQs](/pages/explanation/faq/) <br/>
+    [:octicons-arrow-right-24: Other FAQs](pages/explanation/faq/) <br/>
     [:octicons-arrow-right-24: Where can I ask a question?](pages/explanation/contributing/#got-a-vizro-question) <br/>
 
 

diff --git a/vizro-core/docs/pages/explanation/documentation-style-guide.md b/vizro-core/docs/pages/explanation/documentation-style-guide.md
@@ -6,7 +6,7 @@ This is the style guide we apply to the [Vizro documentation](https://vizro.read
 
 We ask anyone kind enough to contribute documentation changes to follow this style for consistency and simplicity.
 
-What follows is a set of lightweight guidelines rather than rules. There are always edge cases and exceptions, and if it's not obvious what the style should be, consult the [Microsoft style guide](https://docs.microsoft.com/en-gb/style-guide/welcome/) for an example of good practice. We also use the [INCITS Inclusive Terminology Guidelines](https://standards.incits.org/apps/group_public/download.php/131246/eb-2021-00288-001-INCITS-Inclusive-Terminology-Guidelines.pdf).
+What follows is a set of lightweight guidelines rather than rules. There are always edge cases and exceptions, and if it's not obvious what the style should be, consult the [Microsoft style guide](https://docs.microsoft.com/en-gb/style-guide/welcome/) for an example of good practice. We also [ensure inclusive terminology](https://developers.google.com/style/inclusive-documentation) with the Google developer documentation style guide.
 
 ## Vizro lexicon
 

diff --git a/vizro-core/hatch.toml b/vizro-core/hatch.toml
@@ -66,10 +66,17 @@ dependencies = [
   "mkdocs",
   "mkdocs-material",
   "mkdocs-git-revision-date-localized-plugin",
-  "mkdocstrings[python]"
+  "mkdocstrings[python]",
+  "linkchecker"
 ]
 detached = true
-scripts = {serve = "mkdocs serve --strict"}
+
+[envs.docs.scripts]
+build = "mkdocs build --strict"
+# Disable warnings on the linkcheck so that HTTP redirects are accepted. We could ignore only that warning and specify
+# more advanced settings using a linkcheckerrc config file.
+link-check = "linkchecker site --check-extern --no-warnings --ignore=404.html --ignore-url=127.0.0.1"
+serve = "mkdocs serve --strict"
 
 [envs.lint]
 dependencies = [