From fb72f3ad52769ad470cd1f7fc36f76b53853f3e8 Mon Sep 17 00:00:00 2001 From: Brennan Kinney <5098581+polarathene@users.noreply.github.com> Date: Sun, 31 Oct 2021 09:13:18 +1300 Subject: [PATCH] ci(docs): Fail when build aborts from broken links (#2266) Using `set -ex` will exit the script as soon as a non-zero exit code is returned, such as when the docker image fails building the docs due to `build --strict` catching broken links. This also removes the need for `|| exit` when changing directory. This seems fine for a small script, but AFAIK an alternative fix is just adding `|| exit` to the end of the `docker run` command too? There appears to be advice [against adopting `-e` carelessly](http://mywiki.wooledge.org/BashFAQ/105), while others [encourage `-e`](http://redsymbol.net/articles/unofficial-bash-strict-mode/). I know that several maintainers here have preference towards `set -e` so I've kept the original PR solution. Additionally: - `-x` is used to improve command visibility when reviewing the workflow log output. - `--name` isn't necessary, but was part of the original PR. - I've chosen not to include `-o pipefail`, only because no pipes are used in this script. * docs(fix): Fix broken links * ci(docs): Added inline docs Extra documentation context for maintainers to quickly grok what's going on. * chore(docs): Minor typo fix by wernerfred Added from their related PR by request. --- .github/workflows/scripts/docs/build-docs.sh | 9 +++++++-- docs/content/config/environment.md | 4 ++-- docs/content/config/user-management/accounts.md | 2 +- docs/content/examples/tutorials/basic-installation.md | 4 ++-- .../forward-only-mailserver-with-ldap-authentication.md | 2 +- 5 files changed, 13 insertions(+), 8 deletions(-) diff --git a/.github/workflows/scripts/docs/build-docs.sh b/.github/workflows/scripts/docs/build-docs.sh index 75a435c0..6dab6700 100755 --- a/.github/workflows/scripts/docs/build-docs.sh +++ b/.github/workflows/scripts/docs/build-docs.sh @@ -1,15 +1,20 @@ #!/bin/bash +set -ex +# PWD should be at the project docs/ folder. # `--user` is required for build output file ownership to match the CI user, # instead of the internal root user of the container. +# `build --strict` ensures the build fails when any warnings are omitted. docker run \ --rm \ --user "$(id -u):$(id -g)" \ - -v "${PWD}:/docs" \ + --volume "${PWD}:/docs" \ + --name "build-docs" \ squidfunk/mkdocs-material:7.3.5 build --strict # Remove unnecessary build artifacts: https://github.com/squidfunk/mkdocs-material/issues/2519 -cd site || exit +# site/ is the build output folder. +cd site find . -type f -name '*.min.js.map' -delete -o -name '*.min.css.map' -delete rm sitemap.xml.gz rm assets/images/favicon.png diff --git a/docs/content/config/environment.md b/docs/content/config/environment.md index 7b380d65..8a6d0f9b 100644 --- a/docs/content/config/environment.md +++ b/docs/content/config/environment.md @@ -721,8 +721,8 @@ you to replace both instead of just the envelope sender. - password for default relay user [docs-faq-onedir]: ../faq.md#what-is-the-mail-state-folder-for -[docs-tls]: ./config/security/ssl.md +[docs-tls]: ./security/ssl.md [docs-tls-letsencrypt]: ./security/ssl.md#lets-encrypt-recommended [docs-tls-manual]: ./security/ssl.md#bring-your-own-certificates [docs-tls-selfsigned]: ./security/ssl.md#self-signed-certificates -[docs-accounts]: ./config/user-management/accounts.md#notes +[docs-accounts]: ./user-management/accounts.md#notes diff --git a/docs/content/config/user-management/accounts.md b/docs/content/config/user-management/accounts.md index 49ba3005..56bb0224 100644 --- a/docs/content/config/user-management/accounts.md +++ b/docs/content/config/user-management/accounts.md @@ -41,7 +41,7 @@ You will then be asked for a password, and be given back the data for a new acco - `imap-quota` is enabled and allow clients to query their mailbox usage. - When the mailbox is deleted, the quota directive is deleted as well. -- Dovecot quotas support LDAP, **but it's not implemented** (_PR are welcome!_). +- Dovecot quotas support LDAP, **but it's not implemented** (_PRs are welcome!_). [docs-setupsh]: ../setup.sh.md [github-issue-552]: https://github.com/docker-mailserver/docker-mailserver/issues/552 diff --git a/docs/content/examples/tutorials/basic-installation.md b/docs/content/examples/tutorials/basic-installation.md index 0ee2d66f..bef66996 100644 --- a/docs/content/examples/tutorials/basic-installation.md +++ b/docs/content/examples/tutorials/basic-installation.md @@ -144,8 +144,8 @@ In this setup `docker-mailserver` is not intended to receive email externally, s [docs-ports]: ../../config/security/understanding-the-ports.md [docs-setup-script]: ../../config/setup.sh.md [docs-environment]: ../../config/environment.md -[docs-spf]: ../../config/best-practice/spf.md -[docs-dkim]: ../../config/best-practice/dkim.md +[docs-spf]: ../../config/best-practices/spf.md +[docs-dkim]: ../../config/best-practices/dkim.md [docs-ssl]: ../../config/security/ssl.md#lets-encrypt-recommended [github-issue-1405-comment]: https://github.com/docker-mailserver/docker-mailserver/issues/1405#issuecomment-590106498 diff --git a/docs/content/examples/uses-cases/forward-only-mailserver-with-ldap-authentication.md b/docs/content/examples/uses-cases/forward-only-mailserver-with-ldap-authentication.md index c87ab6be..65b75d62 100644 --- a/docs/content/examples/uses-cases/forward-only-mailserver-with-ldap-authentication.md +++ b/docs/content/examples/uses-cases/forward-only-mailserver-with-ldap-authentication.md @@ -108,5 +108,5 @@ You see that besides `query_filter`, I had to customize as well `result_attribut One user reports only having success if `ENABLE_LDAP=0` was set. -[docs-userpatches]: ./config/advanced/override-defaults/user-patches.md +[docs-userpatches]: ../../config/advanced/override-defaults/user-patches.md [github-issue-1247]: https://github.com/docker-mailserver/docker-mailserver/issues/1247