From 45c847be7f70359ae299fa1b6db6b0a94758a726 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Thu, 14 Nov 2024 16:49:42 +0100 Subject: [PATCH 1/2] =?UTF-8?q?=E2=9E=95=20Add=20mkdocs-htmlproofer-plugin?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This plugin validates URLs, including anchors, in rendered html files. To check for broken links locally: CHECK_BROKEN_LINKS=true mkdocs serve --quiet See: https://github.com/manuzhang/mkdocs-htmlproofer-plugin --- README.md | 10 +++++++++- mkdocs.yml | 5 ++++- requirements.in | 1 + requirements.txt | 23 ++++++++++++----------- 4 files changed, 26 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index fb638a8c..37604c20 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,15 @@ MKDOCS_EXPORTER_PDF=true mkdocs build ``` The PDF file is generated in`site/trio-docs.pdf`. - + +### Find Broken Links + +To list broken links, we use [`mkdocs-htmlproofer-plugin`](https://github.com/manuzhang/mkdocs-htmlproofer-plugin): + +```shell +CHECK_BROKEN_LINKS=true mkdocs build --quiet +``` + ## Contribute You can contribute to the Trio documentation by correcting typos or suggesting new content. diff --git a/mkdocs.yml b/mkdocs.yml index b86929f9..b0ee8ce0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,7 +3,7 @@ site_name: TrioDocs site_description: Documentation of Trio, an Automated Insulin Delivery system for iOS. site_url: https://docs.diy-trio.org/ site_author: Trio Community -use_directory_urls: true +use_directory_urls: !ENV [CHECK_BROKEN_LINKS, True] # GitHub Repository repo_name: nightscout/trio-docs @@ -86,6 +86,9 @@ plugins: icon: material-file-download-outline enabled: !!python/name:mkdocs_exporter.formats.pdf.buttons.download.enabled attributes: !!python/name:mkdocs_exporter.formats.pdf.buttons.download.attributes + - htmlproofer: + enabled: !ENV [CHECK_BROKEN_LINKS, False] + raise_error_after_finish: true - search extra_css: diff --git a/requirements.in b/requirements.in index b412d4b0..2a48c6b1 100644 --- a/requirements.in +++ b/requirements.in @@ -3,5 +3,6 @@ mkdocs-exporter==6.1.1 mkdocs-material>=9.5.9 mkdocs-include-markdown-plugin>=6.0.4 mkdocs-exclude>=1.0.2 +mkdocs-htmlproofer-plugin>=1.3.0 mkdocs-open-in-new-tab==1.0.6 mkdocs-macros-plugin>=1.0.4 diff --git a/requirements.txt b/requirements.txt index 36cc9c6d..3592d598 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,37 +6,38 @@ charset-normalizer==3.4.0 click==8.1.7 colorama==0.4.6 ghp-import==2.1.0 -greenlet==3.0.3 +greenlet==3.1.1 hjson==3.1.0 idna==3.10 Jinja2==3.1.4 libsass==0.23.0 lxml==5.3.0 Markdown==3.7 -MarkupSafe==3.0.1 +MarkupSafe==3.0.2 mergedeep==1.3.4 mkdocs==1.6.1 mkdocs-exclude==1.0.2 mkdocs-exporter==6.1.1 mkdocs-get-deps==0.2.0 -mkdocs-include-markdown-plugin==6.2.2 -mkdocs-macros-plugin==1.3.5 -mkdocs-material==9.5.40 +mkdocs-htmlproofer-plugin==1.3.0 +mkdocs-include-markdown-plugin==7.0.0 +mkdocs-macros-plugin==1.3.7 +mkdocs-material==9.5.44 mkdocs-material-extensions==1.3.1 mkdocs-open-in-new-tab==1.0.6 -packaging==24.1 +packaging==24.2 paginate==0.5.7 pathspec==0.12.1 platformdirs==4.3.6 -playwright==1.47.0 +playwright==1.48.0 pyee==12.0.0 Pygments==2.18.0 -pymdown-extensions==10.11.2 -pypdf==5.0.1 +pymdown-extensions==10.12 +pypdf==5.1.0 python-dateutil==2.9.0.post0 PyYAML==6.0.2 pyyaml_env_tag==0.1 -regex==2024.9.11 +regex==2024.11.6 requests==2.32.3 six==1.16.0 soupsieve==2.6 @@ -44,5 +45,5 @@ super_collections==0.5.3 termcolor==2.5.0 typing_extensions==4.12.2 urllib3==2.2.3 -watchdog==5.0.3 +watchdog==6.0.0 wcmatch==10.0 From 464eac60c14bfed9cdd89c1cc2f61423595c890d Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Thu, 14 Nov 2024 21:39:40 +0100 Subject: [PATCH 2/2] =?UTF-8?q?=E2=9C=8F=EF=B8=8F=20Fix=20broken=20links?= =?UTF-8?q?=20in=20the=20build=20page?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/operate/build.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/operate/build.md b/docs/operate/build.md index d96b286f..6f936cc4 100644 --- a/docs/operate/build.md +++ b/docs/operate/build.md @@ -142,7 +142,7 @@ If you build Trio on your Mac using Xcode, the recommendation is to use the [**T ### Build Trio with Script -The **`TrioBuildSelectScript`** is similar to the script used to build Loop. If you need it, extensive instructions for that script are provided at these links: [LoopDocs: Build Select Script](https://loopkit.github.io/loopdocs/build/step14/#build-select-script) and [Loop and Learn: Build Select Script](https://www.loopandlearn.org/build-select/). +The **`TrioBuildSelectScript`** is similar to the script used to build Loop. If you need it, extensive instructions for that script are provided at these links: [LoopDocs: Build Select Script](https://loopkit.github.io/loopdocs/build/build-app/#build-select-script) and [Loop and Learn: Build Select Script](https://www.loopandlearn.org/build-select/). The **`TrioBuildSelectScript`** offers the choice to: @@ -198,7 +198,7 @@ For more information, refer to [Loop and Learn: Maintenance Utitilites](https:// ### Build Errors -If you encounter any build issues, please look at the [LoopDocs Build](https://loopkit.github.io/loopdocs/build/build_errors/) errors page. Only some things on that page are relevant for building Trio, but many potential issues will likely be covered there. You will also get helpful advice about what info to provide if you need to ask for help. When you have identified the error message(s), you can use the search tool in LoopDocs to see if your error is mentioned. +If you encounter any build issues, please look at the [LoopDocs Build](https://loopkit.github.io/loopdocs/build/build-errors/) errors page. Only some things on that page are relevant for building Trio, but many potential issues will likely be covered there. You will also get helpful advice about what info to provide if you need to ask for help. When you have identified the error message(s), you can use the search tool in LoopDocs to see if your error is mentioned. If you need it, you are most likely to get help in one of these groups: