ci: lint docs in all directories (#98)

Files like README.md and HACKING.md are linted by sphinx-lint.

Signed-off-by: Callahan Kovacs <[email protected]>

.gitignore

@@ -139,3 +139,6 @@ dmypy.json
 
 # Ignore version module generated by setuptools_scm
 /*/_version.py
+
+# Visual Studio Code
+.vscode/

HACKING.rst

@@ -2,23 +2,32 @@
 Starcraft
 *********
 
-Welcome to Starcraft! We hope this document helps you get started. Before contributing any code, please sign the `Canonical contributor licence agreement`_.
+Welcome to Starcraft! We hope this document helps you get started. Before
+contributing any code, please sign the `Canonical contributor licence
+agreement`_.
 
 Setting up a development environment
 ------------------------------------
-We use a forking, feature-based workflow, so you should start by forking the repository. Once you've done that, clone the project to your computer using git clone's ``--recurse-submodules`` parameter. (See more on the `git submodules`_ documentation.)
+We use a forking, feature-based workflow, so you should start by forking the
+repository. Once you've done that, clone the project to your computer using git
+clone's ``--recurse-submodules`` parameter. (See more on the `git submodules`_
+documentation.)
 
 Tooling
 =======
-We use a large number of tools for our project. Most of these are installed for you with tox, but you'll need to install:
+We use a large number of tools for our project. Most of these are installed for
+you with tox, but you'll need to install:
 
-- Python 3.8 (default on Ubuntu 20.04, available on Ubuntu 22.04 through the deadsnakes_ PPA) with setuptools.
+- Python 3.8 (default on Ubuntu 20.04, available on Ubuntu 22.04 through the
+  deadsnakes_ PPA) with setuptools.
 - tox_ version 4 or later. (3.8+ will automatically provision a v4 virtualenv)
-- Pyright_ (it's recommended you install with ``snap install --classic pyright``)
+- Pyright_ (it's recommended you install with ``snap install --classic
+  pyright``)
 - ShellCheck_  (also available via snap: ``snap install shellcheck``)
 - pre-commit_
 
-Once you have all of those installed, you can install the necessary virtual environments for this repository using tox.
+Once you have all of those installed, you can install the necessary virtual
+environments for this repository using tox.
 
 Other tools
 ###########
@@ -33,19 +42,30 @@ A complete list is kept in our pyproject.toml_ file in dev dependencies.
 Initial Setup
 #############
 
-After cloning the repository but before making any changes, it's worth ensuring that the tests, linting and tools all run on your machine. Running ``tox`` with no parameters will create the necessary virtual environments for linting and testing and run those::
+After cloning the repository but before making any changes, it's worth ensuring
+that the tests, linting and tools all run on your machine. Running ``tox`` with
+no parameters will create the necessary virtual environments for linting and
+testing and run those::
 
     tox
 
 If you want to install the environments but not run the tests, you can run::
 
     tox --notest
 
-If you'd like to run the tests with a newer version of Python, you can pass a specific environment. You must have an appropriately versioned Python interpreter installed. For example, to run with Python 3.10, run::
+If you'd like to run the tests with a newer version of Python, you can pass a
+specific environment. You must have an appropriately versioned Python
+interpreter installed. For example, to run with Python 3.10, run::
 
     tox -e test-py310
 
-While the use of pre-commit_ is optional, it is highly encouraged, as it runs automatic fixes for files when `git commit` is called, including code formatting with ``black`` and ``ruff``.  The versions available in ``apt`` from Debian 11 (bullseye), Ubuntu 22.04 (jammy) and newer are sufficient, but you can also install the latest with ``pip install pre-commit``. Once you've installed it, run ``pre-commit install`` in this git repository to install the pre-commit hooks.
+While the use of pre-commit_ is optional, it is highly encouraged, as it runs
+automatic fixes for files when ``git commit`` is called, including code
+formatting with ``black`` and ``ruff``.  The versions available in ``apt`` from
+Debian 11 (bullseye), Ubuntu 22.04 (jammy) and newer are sufficient, but you can
+also install the latest with ``pip install pre-commit``. Once you've installed
+it, run ``pre-commit install`` in this git repository to install the pre-commit
+hooks.
 
 Tox environments and labels
 ###########################
@@ -59,13 +79,15 @@ We group tox environments with the following labels:
 * ``integration-tests``: Same as above but for integration tests
 * ``tests``: The union of ``unit-tests`` and ``integration-tests``
 
-For each of these, you can see which environments will be run with ``tox list``. For example:
+For each of these, you can see which environments will be run with ``tox list``.
+For example::
 
     tox list -m lint
 
 You can also see all the environments by simply running ``tox list``
 
-Running ``tox run -m format`` and ``tox run -m lint`` before committing code is recommended.
+Running ``tox run -m format`` and ``tox run -m lint`` before committing code is
+recommended.
 
 .. _Black: https://black.readthedocs.io
 .. _`Canonical contributor licence agreement`: http://www.ubuntu.com/legal/contributors/

README.rst

@@ -6,7 +6,9 @@ A base repository for Starcraft projects.
 
 Description
 -----------
-This project is designed to act as the basis for any future starcraft projects as well as a testbed for any tooling changes we want to make before merging them into other projects.
+This project is designed to act as the basis for any future starcraft projects
+as well as a testbed for any tooling changes we want to make before merging
+them into other projects.
 
 Structure
 ---------
@@ -20,14 +22,17 @@ How to create a new project
 ---------------------------
 [TODO: Make this a template repository.]
 
-1. [Use this template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) to create your repository.
-2. Ensure the ``LICENSE`` file represents the current best practices from the Canonical legal team for the specific project you intend to release. (LGPL v3 for libraries, GPL v3 for applications.)
-3. Rename any files or directories and ensure references are updated.
-4. Replace any appropriate `starcraft` references with the appropriate name.
-5. Put correct contact information into CODE_OF_CONDUCT.md
-6. Write a new README
-7. Import your documentation to ReadTheDocs_.
+#. `Use this template`_ to create your repository.
+#. Ensure the ``LICENSE`` file represents the current best practices from the
+   Canonical legal team for the specific project you intend to release. (LGPL v3
+   for libraries, GPL v3 for applications.)
+#. Rename any files or directories and ensure references are updated.
+#. Replace any appropriate ``starcraft`` references with the appropriate name.
+#. Put correct contact information into CODE_OF_CONDUCT.md
+#. Write a new README
+#. Import your documentation to ReadTheDocs_.
 
 .. _EditorConfig: https://editorconfig.org/
 .. _pre-commit: https://pre-commit.com/
 .. _ReadTheDocs: https://docs.readthedocs.io/en/stable/intro/import-guide.html
+.. _use this template: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template

tox.ini

@@ -116,8 +116,13 @@ description = Build documentation with an autoupdating server
 base = docs
 commands = sphinx-autobuild {posargs:-b html --open-browser --port 8080} -W --watch {tox_root}/starcraft {tox_root}/docs {tox_root}/docs/_build
 
+[lint-docs]
+find = git ls-files
+
 [testenv:lint-docs]
 description = Lint the documentation with sphinx-lint
 base = docs
-commands = sphinx-lint --ignore docs/_build --max-line-length 80 -e all {posargs} docs/
 labels = lint
+allowlist_externals = bash, xargs
+commands_pre = bash -c '{[lint-docs]find} > {env_tmp_dir}/lint_docs_files'
+commands = xargs --no-run-if-empty --arg-file {env_tmp_dir}/lint_docs_files sphinx-lint --max-line-length 80 --enable all {posargs}