Add vale and fix issues detected (#12257)

ericholscher · web-flow · commit 616482ad8b39 · 2025-06-19T05:12:41.000-07:00
This is an initial run of Vale, based off of #9521 I wasn't able to update that PR, so pulling that one in here. We can add more rules as we go.  --- :books: Documentation previews :books: - User's documentation (`docs`): https://docs--12257.org.readthedocs.build/12257/   - Developer's documentation (`dev`): https://dev--12257.org.readthedocs.build/12257/
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -61,6 +61,7 @@ jobs:
       - run: pip install --user tox
       - run: tox -e pre-commit
       - run: tox -e migrations
+      - run: tox -e vale
       - save_cache:
           key: pre-commit-cache-{{ checksum "pre-commit-cache-key.txt" }}
           paths:
diff --git a/.vale.ini b/.vale.ini
@@ -0,0 +1,10 @@
+StylesPath = docs/vale/
+MinAlertLevel = suggestion
+
+[*.rst]
+
+BasedOnStyles = Vale, RTD
+Vale.Repetition = YES
+
+# TODO: Enable spelling, but it's currently too noisy
+Vale.Spelling = NO
diff --git a/docs/dev/design/build-images.rst b/docs/dev/design/build-images.rst
@@ -427,7 +427,7 @@ Exposing users how we want them to use our platform will allow us to be able to
 than giving the option to select a specific Docker image by name that we can't guarantee it will be frozen.
 
 Finally, having the ability to deprecate and *remove* pre-built images from our builders over time,
-will reduce the maintenance work required from the the core team.
+will reduce the maintenance work required from the core team.
 We can always support all the languages versions by installing them at build time.
 The only required pre-built image for this are the OS ``-base`` images.
 In fact, even after decided to deprecate and removed a pre-built image from the builders,
diff --git a/docs/dev/design/new-search-api.rst b/docs/dev/design/new-search-api.rst
@@ -309,7 +309,7 @@ Future features
 
   - Multi match (query as is)
   - Simple query string (allows using the ES query syntax)
-  - Fuzzy search (same as multi match, but with with fuzziness)
+  - Fuzzy search (same as multi match, but with fuzziness)
 
 - Add the ``org`` filter,
   so users can search by all projects that belong
diff --git a/docs/dev/design/redirects.rst b/docs/dev/design/redirects.rst
@@ -250,7 +250,7 @@ Improving page redirects
   without having to create an exact redirect for each version.
 
   Similar to exact redirects, users need to add the ``:splat`` placeholder explicitly.
-  This means that that page redirects are the same as exact redirects,
+  This means that page redirects are the same as exact redirects,
   with the only difference that they apply to all versions.
 
   Example:
diff --git a/docs/dev/design/sphinx-jquery.rst b/docs/dev/design/sphinx-jquery.rst
@@ -92,7 +92,7 @@ When setting ``jquery_force_enable=True``, jQuery is added no matter the Sphinx
 jQuery version and inclusion
 ----------------------------
 
-jQuery should be be shipped together with the Python package and not be referenced from a CDN.
+jQuery should be shipped together with the Python package and not be referenced from a CDN.
 
 Sphinx has kept relatively up to date with jQuery, and this package intends to follow.
 The most recently bundled jQuery version was v3.5.1 and only two releases have happened since: 3.6.0 and 3.6.1.
diff --git a/docs/dev/style-guide.rst b/docs/dev/style-guide.rst
@@ -56,7 +56,7 @@ ReStructuredText for both the RTD user documentation and this developer document
 whitespace consistency, and other minor issues.
 
 You can fix many linting issues automatically by installing and running `pre-commit` locally.
-To run it on content you have have already committed, use the ``--from-ref`` and ``--to-ref`` `flags <https://pre-commit.com/#pre-commit-run>`__.
+To run it on content you have already committed, use the ``--from-ref`` and ``--to-ref`` `flags <https://pre-commit.com/#pre-commit-run>`__.
 
 .. code-block:: bash
 
diff --git a/docs/user/build-customization.rst b/docs/user/build-customization.rst
@@ -98,7 +98,7 @@ Where to put files
 It is your responsibility to generate HTML and other formats of your documentation when overriding the steps from :ref:`config-file/v2:build.jobs.build`.
 The contents of the ``$READTHEDOCS_OUTPUT/<format>/`` directory will be hosted as part of your documentation.
 
-We store the the base folder name ``_readthedocs/`` in the environment variable ``$READTHEDOCS_OUTPUT`` and encourage that you use this to generate paths.
+We store the base folder name ``_readthedocs/`` in the environment variable ``$READTHEDOCS_OUTPUT`` and encourage that you use this to generate paths.
 
 Supported :ref:`formats <downloadable-documentation:accessing offline formats>` are published if they exist in the following directories:
 
diff --git a/docs/user/faq.rst b/docs/user/faq.rst
@@ -109,7 +109,7 @@ How do I add additional software dependencies for my documentation?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 For most Python dependencies,
-you can can specify a requirements file which details your dependencies.
+you can specify a requirements file which details your dependencies.
 You can also set your project documentation to install your Python project itself as a dependency.
 
 .. seealso::
diff --git a/docs/user/gsoc.rst b/docs/user/gsoc.rst
@@ -38,7 +38,7 @@ Getting started
 The :doc:`rtd-dev:install` doc is probably the best place to get going.
 It will walk you through getting a basic environment for Read the Docs setup.
 
-Then you can look through our :doc:`rtd-dev:contribute` doc for information on how to get started contributing to RTD.
+Then you can look through our :doc:`rtd-dev:contribute` doc for information on how to get started contributing to Read the Docs.
 
 People who have a history of submitting pull requests will be prioritized in our Summer of Code selection process.
 
diff --git a/docs/user/guides/private-python-packages.rst b/docs/user/guides/private-python-packages.rst
@@ -76,7 +76,7 @@ Here ``BITBUCKET_USER`` is your Bitbucket user.
 
    Bitbucket doesn't support app passwords per repository.
    An app password will grant read access to all repositories the user has access to.
-   You can create a a `machine user <https://confluence.atlassian.com/bitbucketserver/ssh-access-keys-for-system-use-776639781.html>`__ to give read access only to the repositories you need.
+   You can create a `machine user <https://confluence.atlassian.com/bitbucketserver/ssh-access-keys-for-system-use-776639781.html>`__ to give read access only to the repositories you need.
 
 From a repository manager other than PyPI
 -----------------------------------------
diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst
@@ -447,7 +447,7 @@ rather than ``latest``,
 so that users see the ``stable`` documentation
 when they visit the :term:`root URL` of your documentation:
 
-#. In the the :guilabel:`⚙ Admin` menu of your project home, go to the :guilabel:`Settings` link, choose ``stable`` in the "Default version*" dropdown, and hit :guilabel:`Save` at the bottom.
+#. In the :guilabel:`⚙ Admin` menu of your project home, go to the :guilabel:`Settings` link, choose ``stable`` in the "Default version*" dropdown, and hit :guilabel:`Save` at the bottom.
 
 Modifying versions
 ~~~~~~~~~~~~~~~~~~
diff --git a/docs/user/versions.rst b/docs/user/versions.rst
@@ -57,7 +57,7 @@ Each version of your documentation has a state that changes the visibility of it
   Hidden versions are listed as ``Disallow: /path/to/version/``
   in the default :doc:`/reference/robots` created by Read the Docs.
 
-**Public** or **Private** (only available on on :doc:`/commercial/index`)
+**Public** or **Private** (only available on :doc:`/commercial/index`)
   - **Public** versions are visible to everyone, and are browsable by unauthenticated users.
   - **Private** versions are available only to people who have permissions to see them.
     They will return a `404 Not Found` when visited by people without viewing permissions.
diff --git a/docs/vale/RTD/sso.yaml b/docs/vale/RTD/sso.yaml
@@ -0,0 +1,9 @@
+extends: substitution
+message: Use 'Single sign-on' instead of '%s'
+level: warning
+swap:
+  Single Sign-On: Single sign-on
+  Single Sign on: Single sign-on
+  single sign-on: Single sign-on
+  single Sign-On: Single sign-on
+  single Sign on: Single sign-on
diff --git a/docs/vale/RTD/style.yml b/docs/vale/RTD/style.yml
@@ -0,0 +1,7 @@
+extends: substitution
+message: Use '%s' instead of '%s'
+level: error
+swap:
+  Read The Docs: Read the Docs
+  RTD: Read the Docs
+  ReadTheDocs: Read the Docs
diff --git a/tox.ini b/tox.ini
@@ -79,3 +79,12 @@ commands =
     coverage report --show-missing
     coverage html
     echo Annotated HTML coverage report is in {toxinidir}/htmlcov/index.html
+
+[testenv:vale]
+description = Run Vale to check the documentation for style issues
+changedir = {toxinidir}
+deps =
+  vale
+  docutils  # Ensure rst2html is available
+commands =
+    vale docs/user/
