This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "Evergreen ILS". The branch, main has been updated via 5b0cb10c8507b59a497b894f1f85a84fa9520b13 (commit) via 99b0d94444108f4813132089a74fa7adc8e36e1b (commit) from 6c5adbd019f031576a4f584ea0ef6a26a6870375 (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- commit 5b0cb10c8507b59a497b894f1f85a84fa9520b13 Author: Jane Sandberg <js7389@princeton.edu> Date: Tue Nov 26 14:21:58 2024 -0800 LP2076555: incorporate feedback from review This adds information about the vale check to the instructions for committing documentation, where it will be more visible to docs contributors. Thanks to Ruth Davis and others at the collaborative code review! Signed-off-by: Jane Sandberg <js7389@princeton.edu> Signed-off-by: blake <blake@mobiusconsortium.org> diff --git a/docs/modules/shared/assets/images/how_to_contribute_docs/checkmark_pr.png b/docs/modules/shared/assets/images/how_to_contribute_docs/checkmark_pr.png new file mode 100644 index 0000000000..873564363f Binary files /dev/null and b/docs/modules/shared/assets/images/how_to_contribute_docs/checkmark_pr.png differ diff --git a/docs/modules/shared/pages/how_to_contribute_docs.adoc b/docs/modules/shared/pages/how_to_contribute_docs.adoc index ba4389fc16..9a6d425aac 100644 --- a/docs/modules/shared/pages/how_to_contribute_docs.adoc +++ b/docs/modules/shared/pages/how_to_contribute_docs.adoc @@ -199,6 +199,16 @@ image::how_to_contribute_docs/github_web_create_pull_request.png[Github Web Crea . It's nice to see "Able to merge" . Confirm that this pull request is compared with *master* on the left and with *your branch* on the right . Click on "Create pull request" +. Github will run a few checks, to make sure that your changes match our style guide + and won't cause problems when they are published on docs.evergreen-ils.org. These checks will take a few minutes. + * If everything is good, Github will add a green + checkmark icon next to your pull request. ++ +image::how_to_contribute_docs/checkmark_pr.png[A github pull request shows a green checkmark icon immediately after the title of the pull request] ++ + * If there is an issue, Github will add a red X icon. You can click the red X + icon for more details. To address the issue, you can adjust your version of + the docs locally, commit your changes, and publish your branch again. == Follow up on Launchpad == commit 99b0d94444108f4813132089a74fa7adc8e36e1b Author: Jane Sandberg <js7389@princeton.edu> Date: Thu Sep 5 16:50:03 2024 -0700 LP2076555: Use vale to check our documentation for missing alt text Release-note: Add an automated accessibility check for Evergreen's documentation. Signed-off-by: Jane Sandberg <js7389@princeton.edu> diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c24fef336b..9f614c219c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -22,3 +22,16 @@ jobs: name: built-docs path: docs/output retention-days: 2 + check_docs_styles: + name: Check docs styles + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Install asciidoctor + run: sudo apt-get install -y asciidoctor + - name: Install vale + run: pip install vale + - name: Download and install vale rules + run: cd docs && vale sync + - name: Check documentation against DIG style guide + run: cd docs && vale modules diff --git a/docs/.gitignore b/docs/.gitignore index 54ad0c952f..8b417cd1c6 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -4,3 +4,4 @@ package-lock.json build output site-working.yml +vale-styles/AsciiDoc diff --git a/docs/.vale.ini b/docs/.vale.ini new file mode 100644 index 0000000000..cf8ef225a8 --- /dev/null +++ b/docs/.vale.ini @@ -0,0 +1,8 @@ +StylesPath = vale-styles + +MinAlertLevel = suggestion + +Packages = AsciiDoc + +[*.adoc] +AsciiDoc.ImageContainsAltText = error diff --git a/docs/README.adoc b/docs/README.adoc index d25b17ab76..61afe32a84 100644 --- a/docs/README.adoc +++ b/docs/README.adoc @@ -138,3 +138,20 @@ NOTE: https://blog.anoff.io/2019-02-15-antora-first-steps/ NOTE: https://owncloud.org/news/owncloud-docs-migrating-antora-pt-1-2/ +== Checking the documentation against our style guide + +We use a tool named Vale to check our documentation +against our style guide. + +To check it locally: + +. https://asciidoctor.org/#installation[Install asciidoctor locally] +. https://vale.sh/docs/vale-cli/installation/[Install vale locally] +. Run the following commands from the Evergreen source directory: + +[source,bash] +---- +cd docs +vale sync +vale modules +---- ----------------------------------------------------------------------- Summary of changes: .github/workflows/docs.yml | 13 +++++++++++++ docs/.gitignore | 1 + docs/.vale.ini | 8 ++++++++ docs/README.adoc | 17 +++++++++++++++++ .../images/how_to_contribute_docs/checkmark_pr.png | Bin 0 -> 22737 bytes docs/modules/shared/pages/how_to_contribute_docs.adoc | 10 ++++++++++ 6 files changed, 49 insertions(+) create mode 100644 docs/.vale.ini create mode 100644 docs/modules/shared/assets/images/how_to_contribute_docs/checkmark_pr.png hooks/post-receive -- Evergreen ILS