Replace doc8 with sphinx-lint (#16431)

Author: miketheman

bin/lint

@@ -15,7 +15,7 @@ find . -name '*.py' -exec python -m pyupgrade --py312-plus {} +
 python -m flake8 .
 python -m black --check --diff *.py warehouse/ tests/
 python -m isort --check *.py warehouse/ tests/
-python -m doc8 --allow-long-titles README.rst CONTRIBUTING.rst docs/ --ignore-path "docs/**/_build/"
+sphinx-lint --enable=all --disable=line-too-long README.rst CONTRIBUTING.rst docs/dev/ --ignore=docs/dev/_build/
 python -m curlylint ./warehouse/templates ./docs/blog
 python -m mypy -p warehouse
 ./bin/flushes

docs/dev/api-reference/xml-rpc.rst

@@ -49,10 +49,10 @@ Changes to XMLRPC API
   incident <https://status.python.org/incidents/grk0k7sz6zkp>`_.
 
 - ``package_releases`` As Warehouse does not support the concept of hidden
-  releases, the `show_hidden` flag now controls whether the latest version or
+  releases, the ``show_hidden`` flag now controls whether the latest version or
   all versions are returned.
 
-- ``release_data`` The `stable_version` flag is always an empty string. It was
+- ``release_data`` The ``stable_version`` flag is always an empty string. It was
   never fully supported anyway.
 
 - ``release_downloads`` and ``top_packages`` No longer supported. Use
@@ -81,7 +81,7 @@ Retrieve the last event's serial id (an ``int``).
 ``changelog_since_serial(since_serial)``
 ++++++++++++++++++++++++++++++++++++++++
 
-Retrieve a list of `(name, version, timestamp, action, serial)` since the
+Retrieve a list of ``(name, version, timestamp, action, serial)`` since the
 event identified by the given ``since_serial``. All timestamps are UTC
 values.
 
@@ -98,20 +98,20 @@ Package querying
 ``package_roles(package_name)``
 +++++++++++++++++++++++++++++++
 
-Retrieve a list of `[role, user]` for a given `package_name`.
-Role is either `Maintainer` or `Owner`.
+Retrieve a list of ``[role, user]`` for a given ``package_name``.
+Role is either ``Maintainer`` or ``Owner``.
 
 ``user_packages(user)``
 +++++++++++++++++++++++
 
-Retrieve a list of `[role, package_name]` for a given `user`.
-Role is either `Maintainer` or `Owner`.
+Retrieve a list of ``[role, package_name]`` for a given ``user``.
+Role is either ``Maintainer`` or ``Owner``.
 
 ``browse(classifiers)``
 +++++++++++++++++++++++
 
-Retrieve a list of `[name, version]` of all releases classified with all of
-the given classifiers. `classifiers` must be a list of Trove classifier
+Retrieve a list of ``[name, version]`` of all releases classified with all of
+the given classifiers. ``classifiers`` must be a list of Trove classifier
 strings.
 
 ``updated_releases(since)``
@@ -143,10 +143,10 @@ Returns a list of name strings.
 .. warning::
   Migrate to using the :doc:`json`.
 
-Retrieve a list of the releases registered for the given `package_name`,
+Retrieve a list of the releases registered for the given ``package_name``,
 ordered by version.
 
-If `show_hidden` is `False` (the default), only the latest version is
+If ``show_hidden`` is ``False`` (the default), only the latest version is
 returned.  Otherwise, all versions are returned.
 
 ``release_urls(package_name, release_version)``
@@ -155,7 +155,7 @@ returned.  Otherwise, all versions are returned.
 .. warning::
   Migrate to using the :doc:`json`.
 
-Retrieve a list of download URLs for the given `release_version`.
+Retrieve a list of download URLs for the given ``release_version``.
 Returns a list of dicts with the following keys:
 
 * filename
@@ -176,7 +176,7 @@ Returns a list of dicts with the following keys:
 .. warning::
   Migrate to using the :doc:`json`.
 
-Retrieve metadata describing a specific `release_version`.
+Retrieve metadata describing a specific ``release_version``.
 Returns a dict with keys for:
 
 * name
@@ -219,7 +219,7 @@ Deprecated Methods
 
 .. warning::
   The following methods are permanently deprecated and will return a
-  `RuntimeError`
+  ``RuntimeError``
 
 ``changelog(since, with_ids=False)``
 ++++++++++++++++++++++++++++++++++++

docs/dev/development/email.rst

@@ -40,7 +40,7 @@ Calling a function with the ``_email`` decorator does the following:
   response
 - A security log is added to the user's account
 - The email is sent using Amazon SES (on production environment)
-- A metric is sent to Datadog named `warehouse.emails.scheduled` with the tags
+- A metric is sent to Datadog named ``warehouse.emails.scheduled`` with the tags
   ``template_name``, ``allow_unverified``, and ``repeat_window``.
 
 .. _testing-e-mails:

docs/dev/development/getting-started.rst

@@ -188,7 +188,7 @@ application.
    (on Windows by editing the config file found at ``C:\Users\<USER>\AppData\Local\Docker\wsl``).
 
    If you are using Linux, you may need to configure the maximum map count to get
-   the `opensearch` up and running. According to the
+   the ``opensearch`` up and running. According to the
    `documentation <https://opensearch.org/docs/2.15/install-and-configure/install-opensearch/index/#important-settings>`_
    this can be set temporarily:
 
@@ -369,7 +369,7 @@ They also have the following Recovery Codes generated:
 Using different accounts will allow you to see different parts of the site,
 and have slightly different experiences.
 
-For example, using `miketheman` will require email verification.
+For example, using ``miketheman`` will require email verification.
 See :ref:`testing-e-mails` for more information on how to see those emails.
 
 Logging in as users without 2FA

docs/dev/development/legacy-application-structure.rst

@@ -40,39 +40,39 @@ The :action parameters are typically submitted through GET URL parameters,
 though some actions are also POST actions.
 
 **could be nuked without fuss**
-  - `display` was used to display a package version but was replaced ages ago
+  - ``display`` was used to display a package version but was replaced ages ago
     by the /<package>/<version> URL structure
-  - all the user-based stuff like `register_form`, `user`, `user_form`,
-    `forgotten_password_form`, `login`, `logout`, `forgotten_password`,
-    `password_reset`, `pw_reset` and `pw_reset_change` will most likely be
+  - all the user-based stuff like ``register_form``, ``user``, ``user_form``,
+    ``forgotten_password_form``, ``login``, ``logout``, ``forgotten_password``,
+    ``password_reset``, ``pw_reset`` and ``pw_reset_change`` will most likely be
     replaced by newer mechanisms in warehouse
-  - `openid_endpoint`, `openid_decide_post` could also be replaced by something
+  - ``openid_endpoint``, ``openid_decide_post`` could also be replaced by something
     else.
-  - `home` is the old home page thing and completely unnecessary
-  - `index` is overwhelming given the number of projects now.
-  - `browse` and `search` are *probably* only referenced by internal links so
+  - ``home`` is the old home page thing and completely unnecessary
+  - ``index`` is overwhelming given the number of projects now.
+  - ``browse`` and ``search`` are *probably* only referenced by internal links so
     should be safe to nuke
-  - `submit_pkg_info` and `display_pkginfo` probably aren't used
-  - `submit_form` and `pkg_edit` will be changing anyway
-  - `files`, `urls`, `role`, `role_form` are old style and will be changing
-  - `list_classifiers` .. this might actually only be used by Richard :)
-  - `claim`, `openid`, `openid_return`, `dropid` are legacy openid login
+  - ``submit_pkg_info`` and ``display_pkginfo`` probably aren't used
+  - ``submit_form`` and ``pkg_edit`` will be changing anyway
+  - ``files``, ``urls``, ``role``, ``role_form`` are old style and will be changing
+  - ``list_classifiers`` .. this might actually only be used by Richard :)
+  - ``claim``, ``openid``, ``openid_return``, ``dropid`` are legacy openid login
     support and will be changing
-  - `clear_auth` "clears" Basic Auth
-  - `addkey`, `delkey` will be changing if we even keep supporting ssh submit
-  - `verify` probably isn't actually used by anyone
-  - `lasthour` is a pubsubhubbub thing - does this even exist any longer?
-  - `json` is never used as a :action invocation, only ever /<package>/json
-  - `gae_file` I'm pretty sure this is not necessary
-  - `rss_regen` manually regens the RSS cached files, not needed
-  - `about` No longer needed.
-  - `delete_user` No longer needed.
-  - `exception` No longer needed.
+  - ``clear_auth`` "clears" Basic Auth
+  - ``addkey``, ``delkey`` will be changing if we even keep supporting ssh submit
+  - ``verify`` probably isn't actually used by anyone
+  - ``lasthour`` is a pubsubhubbub thing - does this even exist any longer?
+  - ``json`` is never used as a :action invocation, only ever /<package>/json
+  - ``gae_file`` I'm pretty sure this is not necessary
+  - ``rss_regen`` manually regens the RSS cached files, not needed
+  - ``about`` No longer needed.
+  - ``delete_user`` No longer needed.
+  - ``exception`` No longer needed.
 
 **will need to retain**
-  - `rss` and `packages_rss` will be in a bunch of peoples` RSS readers
-  - `doap` is most likely referred to
-  - `show_md5` ?
+  - ``rss`` and ``packages_rss`` will be in a bunch of peoples` RSS readers
+  - ``doap`` is most likely referred to
+  - ``show_md5`` ?
 
 **can be deprecated carefully**
-  - `submit`, `upload`, `doc_upload`, `file_upload`,
+  - ``submit``, ``upload``, ``doc_upload``, ``file_upload``,

docs/dev/development/submitting-patches.rst

@@ -61,7 +61,7 @@ Documentation
 -------------
 
 Important information should be documented with prose in the ``docs`` section.
-To ensure it builds and passes `doc8`_ style checks you can run
+To ensure it builds and passes documentation style checks you can run
 ``make dev-docs user-docs`` and ``make lint`` respectively.
 
 
@@ -187,6 +187,5 @@ feature branch at least once while you are working on it.
 .. _`Write comments as complete sentences.`: https://nedbatchelder.com/blog/201401/comments_should_be_sentences.html
 .. _`syntax`: https://sphinx-doc.org/domains.html#info-field-lists
 .. _`Studies have shown`: https://static1.smartbear.co/support/media/resources/cc/book/code-review-cisco-case-study.pdf
-.. _`doc8`: https://github.com/PyCQA/doc8
 .. _`coverage.py`: https://pypi.org/project/coverage
 .. _`the Black Code Style`: https://github.com/psf/black#the-black-code-style

docs/dev/development/token-scanning.rst

@@ -67,7 +67,7 @@ the request at the bottom. If all went well, you should see a ``204`` ('No
 Content').
 
 Whether it worked or not, a bunch of metrics have been issued, you can see them
-in the `notdatadog` container log.
+in the ``notdatadog`` container log.
 
 GitLab Secret Detection
 -----------------------

requirements/lint.in

@@ -1,4 +1,3 @@
-doc8>=1.1.0
 flake8
 curlylint
 pep8-naming
@@ -9,6 +8,7 @@ mypy
 celery-types
 msgpack-types
 mypy-zope
+sphinx-lint
 types-babel
 types-boto3
 types-certifi