Skip to content

Commit

Permalink
Feat: Configurable Vale command + replacement of Woke (#333)
Browse files Browse the repository at this point in the history 
* feat: replace woke with Vale, add Vale filters, adjust Vale commands

* Feat: Make variable for Vale config to facilitate overrides

* [no-ci] feat: woke replacement documentation and features

Needs to wait for an upstream merge into style guide

* fix: spelling

* refactor: tidy Makefile

* fix: feedback button

* fix: Feedback button config (temp)

* Apply suggestions from code review

fix: accept review changes

Co-authored-by: Artem Konev <141050460+akcano@users.noreply.github.com>

---------

Co-authored-by: Artem Konev <141050460+akcano@users.noreply.github.com>
  • Loading branch information
@SecondSkoll @akcano
SecondSkoll and akcano authored Feb 6, 2025
1 parent d0e9358 commit 4f9fc45
Show file tree
Hide file tree
Showing 5 changed files with 79 additions and 84 deletions.
3 changes: 3 additions & 0 deletions docs/.custom_wordlist.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,6 @@ utils
WCAG
xetex
xindy
kustom
wordlist
txt
53 changes: 22 additions & 31 deletions docs/Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ ALLFILES = *.rst **/*.rst
METRICSDIR = $(SOURCEDIR)/.sphinx/metrics
REQPDFPACKS = latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng
CONFIRM_SUDO ?= N
VALE_CONFIG = $(SPHINXDIR)/vale.ini

# Put it first so that "make" without argument is like "make help".
help:
Expand All @@ -40,7 +41,7 @@ help:

.PHONY: full-help woke-install spellcheck-install pa11y-install install run html \
epub serve clean clean-doc spelling spellcheck linkcheck woke \
allmetrics pa11y pdf-prep-force pdf-prep pdf Makefile.sp vale bash
allmetrics pa11y pdf-prep-force pdf-prep pdf Makefile.sp vale-install vale

full-help: $(VENVDIR)
@. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Expand All @@ -61,21 +62,6 @@ $(VENVDIR):
@. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
@touch $(VENVDIR)

woke-install:
@type woke >/dev/null 2>&1 || \
{ \
echo "Installing system-wide \"woke\" snap..."; \
confirm_sudo=$(CONFIRM_SUDO); \
if [ "$$confirm_sudo" != "y" ] && [ "$$confirm_sudo" != "Y" ]; then \
read -p "This requires sudo privileges. Proceed? [y/N]: " confirm_sudo; \
fi; \
if [ "$$confirm_sudo" = "y" ] || [ "$$confirm_sudo" = "Y" ]; then \
sudo snap install woke; \
else \
echo "Installation cancelled."; \
fi \
}

spellcheck-install:
@type aspell >/dev/null 2>&1 || \
{ \
Expand Down Expand Up @@ -118,7 +104,7 @@ clean: clean-doc
rm -rf $(VENVDIR)
rm -rf $(SPHINXDIR)/node_modules/
rm -rf $(SPHINXDIR)/styles
rm -rf $(SPHINXDIR)/vale.ini
rm -rf $(VALE_CONFIG)

clean-doc:
git clean -fx "$(BUILDDIR)"
Expand All @@ -133,23 +119,28 @@ linkcheck: install
. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; }
exit 0

woke: woke-install
woke $(ALLFILES) --exit-1-on-failure \
-c https://raw.githubusercontent.com/canonical/Inclusive-naming/main/config.yml

pa11y: pa11y-install html
find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)

vale: install
@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
@. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py
@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \;
vale-install: install
@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install rst2html vale
@. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py
@printf '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(SPHINXDIR)/styles/woke.filter
@printf '.Level=="error"' > $(SPHINXDIR)/styles/error.filter
@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(VALE_CONFIG)" $(TARGET) > /dev/null \;

woke: vale-install
@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
@cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
@printf "Running Vale acceptable term check against $(TARGET). To change target set TARGET= with make command\n"
@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/woke.filter' --glob='*.{md,rst}' $(TARGET) || true
@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt

vale: vale-install
@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
@cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
@echo ""
@echo "Running Vale against $(TARGET). To change target set TARGET= with make command"
@echo ""
@. $(VENV); vale --config "$(SPHINXDIR)/vale.ini" --glob='*.{md,txt,rst}' $(TARGET) || true
@printf "Running Vale against $(TARGET). To change target set TARGET= with make command\n"
@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/error.filter' --glob='*.{md,rst}' $(TARGET) || true
@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt

pdf-prep: install
Expand Down Expand Up @@ -177,8 +168,8 @@ allmetrics: html
@echo "Checking for existence of vale..."
. $(VENV)
@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
@. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py
@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \;
@. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py
@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(VALE_CONFIG)" $(TARGET) > /dev/null \;
@eval '$(METRICSDIR)/source_metrics.sh $(PWD)'
@eval '$(METRICSDIR)/build_metrics.sh $(PWD) $(METRICSDIR)'

Expand Down
11 changes: 10 additions & 1 deletion docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -135,16 +135,21 @@
# Docs branch in the repo; used in links for viewing the source files
#
# TODO: To customise the branch, uncomment and update as needed.
# 'github_version': 'main',
'github_version': 'main',
# Docs location in the repo; used in links for viewing the source files
#


# TODO: To customise the directory, uncomment and update as needed.
"github_folder": "/docs/",
# TODO: To enable or disable the Previous / Next buttons at the bottom of pages
# Valid options: none, prev, next, both
# "sequential_nav": "both",
# TODO: To enable listing contributors on individual pages, set to True
"display_contributors": False,

# Required for feedback button
'github_issues': 'enabled',
}

# Project slug; see https://meta.discourse.org/t/what-is-category-slug/87897
Expand Down Expand Up @@ -287,6 +292,10 @@
:class: align-center
.. role:: h2
:class: hclass2
.. role:: woke-ignore
:class: woke-ignore
.. role:: vale-ignore
:class: vale-ignore
"""

# Workaround for https://github.com/canonical/canonical-sphinx/issues/34
Expand Down
90 changes: 44 additions & 46 deletions docs/content/automatic_checks_inclusivelanguage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,80 +3,78 @@
Inclusive language check
========================

The inclusive language check uses `woke`_ to check for violations of inclusive language guidelines.
The inclusive language check uses `Vale`_ to check for violations of inclusive language guidelines.

Install prerequisite software
-----------------------------
Run the inclusive language check
--------------------------------

The following two commands can be run from any location on your system.
Run the following command from within your documentation folder::

To install ``woke``, you need ``snap``::
make woke

sudo apt install snapd
Configure the inclusive language check
--------------------------------------

To install ``woke``:
By default, the inclusive language check is applied to Markdown and |RST| files located in the documentation folder (usually :file:`docs/`).

.. code-block:: bash
Inclusive language check exemptions
-----------------------------------

make woke-install
Sometimes, you might need to use some non-inclusive words.
In such cases, you may exclude them from the check.

Run the inclusive language check
--------------------------------
Exempt a word in a single instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Run the following command from within your documentation folder.
To exempt an individual word, give the word the ``woke-ignore`` role::

Ensure the documentation uses inclusive language::
:woke-ignore:`<SOME_WORD>`

make woke
For instance::

Configure the inclusive language check
--------------------------------------
This is your text. The word in question is here: :woke-ignore:`whitelist`.

By default, the inclusive language check is applied only to |RST| files located in the documentation folder (usually :file:`docs/`).
To check Markdown files, for example, or to use a location other than the :file:`docs/` sub-tree, you must override the ``ALLFILES`` variable in :file:`Makefile.sp`.
.. note::

You can find more information about available options in the `woke User Guide`_.
Vale will lint the displayed text of a link, not the URL of a link. If you
wish to use a link that contains non-inclusive language, use appropriate link
text with the syntax appropriate for your source file.

Inclusive language check exemptions
-----------------------------------
Exempt a word globally
~~~~~~~~~~~~~~~~~~~~~~

Sometimes, you might need to use some non-inclusive words.
In such cases, create check exemptions for them.
Vale will ignore any word listed in the `.custom_wordlist.txt` file.
To exempt a word, add it to this file globally.

See the `woke documentation`_ for how to do this.
The following sections provide some examples.
.. note::

Exempt a word
~~~~~~~~~~~~~
Entries in `.custom-wordlist` are case-sensitive only when a capitalised word is used. For instance:

To exempt an individual word, place a custom ``none`` role (defined in the ``canonical-sphinx-extensions`` Sphinx extension) anywhere on the line containing the word in question.
The role syntax is::
- Adding `kustom` will cause all instances of `Kustom` and `kustom` to be ignored.
- Adding `Kustom` will cause only instances of `Kustom` to be ignored.

:none:`wokeignore:rule=<SOME_WORD>,`
Exclude multiple lines from a file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For instance::
Vale can be switched on and off within a file using syntax appropriate to that
format.

This is your text. The word in question is here: whitelist. More text. :none:`wokeignore:rule=whitelist,`
To turn Vale off entirely for a section of Markdown::

To exempt an element of a URL, use the standard |RST| method of placing links at the bottom of the page (or in a separate file) and place a comment line immediately above the URL line.
The comment syntax is::
<!-- vale off -->

.. wokeignore:rule=<SOME_WORD>
This text will be ignored.

Here is an example where a URL element contains the string "master": :none:`wokeignore:rule=master,`
<!-- vale on -->

.. code-block:: none
.. important::

.. LINKS
.. wokeignore:rule=master
.. _link definition: https://some-external-site.io/master/some-page.html
Only use this when other options are not suitable.

You can now refer to the label ``link definition_`` in the body of the text.
To turn Vale off entirely for a section of |RST|::

Exempt an entire file
~~~~~~~~~~~~~~~~~~~~~
.. vale off

A more drastic solution is to make an exemption for the contents of an entire file.
For example, to exempt file :file:`docs/foo/bar.rst`, add the following line to the file :file:`.wokeignore`::
This text will be ignored.

foo/bar.rst
.. vale on
6 changes: 0 additions & 6 deletions docs/reuse/links.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,12 @@
.. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs-at-canonical
.. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs
.. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/
.. wokeignore:rule=master
.. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html
.. wokeignore:rule=master
.. _`Sphinx extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html
.. wokeignore:rule=master
.. _`file-wide metadata`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
.. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/
.. _`Hiding Contents sidebar`: https://pradyunsg.me/furo/customisation/toc/
.. _`Sphinx`: https://www.sphinx-doc.org/
.. _woke documentation: https://docs.getwoke.tech/ignore
.. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx
.. _change log: https://github.com/canonical/sphinx-docs-starter-pack/wiki/Change-log
.. _Open Graph: https://ogp.me/
Expand All @@ -24,8 +20,6 @@
.. _Diátaxis: https://diataxis.fr/
.. _Pa11y: https://pa11y.org/
.. _Pa11y readme: https://github.com/pa11y/pa11y#command-line-configuration
.. _woke: https://github.com/get-woke/woke
.. _woke User Guide: https://docs.getwoke.tech/usage/#file-globs
.. _More useful markup: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/#more-useful-markup
.. _Vale: https://vale.sh/
.. _Vale rules: https://github.com/canonical/praecepta
Expand Down

0 comments on commit 4f9fc45

Please sign in to comment.