Rst linting (#285)

* add sphinx-lint and fix issues reported

* fix some other minor issues

.pre-commit-config.yaml

@@ -93,3 +93,8 @@ repos:
       hooks:
           - id: pretty-format-toml
             args: [--autofix]
+
+    - repo: https://github.com/sphinx-contrib/sphinx-lint
+      rev: v0.9.1
+      hooks:
+          - id: sphinx-lint

docs/changelog.rst

@@ -2,7 +2,7 @@
 Changelog
 #########
 
-*[CalVer, YY.month.patch](https://calver.org/)*
+`CalVer, YY.month.patch <https://calver.org/>`_
 
 24.9.1
 ======
@@ -182,7 +182,7 @@ Changelog
 
 22.11.2
 =======
-- TRIO105 now also checks that you ``await``ed ``nursery.start()``.
+- TRIO105 now also checks that you ``await``\ed ``nursery.start()``.
 
 22.11.1
 =======

docs/rules.rst

@@ -84,7 +84,7 @@ _`ASYNC120` : await-in-except
     This is currently not able to detect asyncio shields.
 
 _`ASYNC121`: control-flow-in-taskgroup
-    `return`, `continue`, and `break` inside a :ref:`taskgroup_nursery` can lead to counterintuitive behaviour. Refactor the code to instead cancel the :ref:`cancel_scope` inside the TaskGroup/Nursery and place the statement outside of the TaskGroup/Nursery block. In asyncio a user might expect the statement to have an immediate effect, but it will wait for all tasks to finish before having an effect. See `Trio issue #1493 <https://github.com/python-trio/trio/issues/1493>` for further issues specific to trio/anyio.
+    `return`, `continue`, and `break` inside a :ref:`taskgroup_nursery` can lead to counterintuitive behaviour. Refactor the code to instead cancel the :ref:`cancel_scope` inside the TaskGroup/Nursery and place the statement outside of the TaskGroup/Nursery block. In asyncio a user might expect the statement to have an immediate effect, but it will wait for all tasks to finish before having an effect. See `Trio issue #1493 <https://github.com/python-trio/trio/issues/1493>`_ for further issues specific to trio/anyio.
 
 
 Blocking sync calls in async functions
@@ -194,6 +194,7 @@ _`ASYNC913` : indefinite-loop-no-guaranteed-checkpoint
 Autofix support
 ===============
 The following rules support :ref:`autofixing <autofix>`.
+
 - :ref:`ASYNC100 <ASYNC100>`
 - :ref:`ASYNC910 <ASYNC910>`
 - :ref:`ASYNC911 <ASYNC911>`

docs/usage.rst

@@ -98,9 +98,9 @@ Configuration
 `You can configure flake8 with command-line options <https://flake8.pycqa.org/en/latest/user/invocation.html>`_,
 but we prefer using a config file. See general documentation for `configuring flake8  <https://flake8.pycqa.org/en/latest/user/configuration.html>`_ which also handles options registered by plugins such as ``flake8-async``.
 
-If you want to use a ``pyproject.toml`` file for configuring flake8 we recommend `pyproject-flake8 <https://github.com/csachs/pyproject-flake8>` or similar.
+If you want to use a ``pyproject.toml`` file for configuring flake8 we recommend `pyproject-flake8 <https://github.com/csachs/pyproject-flake8>`_ or similar.
 
-Note that when running ``flake8-async`` as a standalone it's not currently possible to use a configuration file. Consider using some wrapper that lets you specify command-line flags in a file. For example, :ref:`install-run-pre-commit`, `tox <https://tox.wiki>`, `hatch scripts <https://hatch.pypa.io/1.9/environment/#scripts>`, MakeFiles, etc.
+Note that when running ``flake8-async`` as a standalone it's not currently possible to use a configuration file. Consider using some wrapper that lets you specify command-line flags in a file. For example, :ref:`install-run-pre-commit`, `tox <https://tox.wiki>`_, `hatch scripts <https://hatch.pypa.io/1.9/environment/#scripts>`_, MakeFiles, etc.
 
 Selecting rules
 ===============