Merge pull request #9303 from tk0miya/fix_docslint

doc: Fix docslint misunderstanding scope of code-blocks

doc/development/theming.rst

@@ -207,9 +207,9 @@ inside your module:
 First, define the registration function, which accepts the arguments for
 :event:`html-page-context`.
 
-Within the registration function, define the template function that you'd like to use
-within Jinja. The template function should return a string or Python objects (lists,
-dictionaries) with strings inside that Jinja uses in the templating process
+Within the registration function, define the template function that you'd like to
+use within Jinja. The template function should return a string or Python objects
+(lists, dictionaries) with strings inside that Jinja uses in the templating process
 
 .. note::
 

doc/extdev/appapi.rst

@@ -159,7 +159,9 @@ connect handlers to the events.  Example:
 
 Below is an overview of each event that happens during a build. In the list
 below, we include the event name, its callback parameters, and the input and output
-type for that event::
+type for that event:
+
+.. code-block:: none
 
    1. event.config-inited(app,config)
    2. event.builder-inited(app)
@@ -168,18 +170,18 @@ type for that event::
 
    for docname in docnames:
       5. event.env-purge-doc(app, env, docname)
-      
+
       if doc changed and not removed:
          6. source-read(app, docname, source)
          7. run source parsers: text -> docutils.document
             - parsers can be added with the app.add_source_parser() API
          8. apply transforms based on priority: docutils.document -> docutils.document
             - event.doctree-read(app, doctree) is called in the middle of transforms,
               transforms come before/after this event depending on their priority.
-   
+
    9. event.env-merge-info(app, env, docnames, other)
       - if running in parallel mode, this event will be emitted for each process
-   
+
    10. event.env-updated(app, env)
    11. event.env-get-updated(app, env)
    12. event.env-check-consistency(app, env)
@@ -377,7 +379,8 @@ Here is a more detailed list of these events.
    ``'page.html'`` as the HTML template for this page.
 
    .. note:: You can install JS/CSS files for the specific page via
-             :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since v3.5.0.
+             :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since
+             v3.5.0.
 
    .. versionadded:: 0.4
 

doc/faq.rst

@@ -259,7 +259,9 @@ The following list gives some hints for the creation of epub files:
 
      ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
 
-  If you get the following error, fix your document structure::
+  If you get the following error, fix your document structure:
+
+  .. code-block:: none
 
      Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
      Error(prcgen):E24001: The table of content could not be built.

doc/usage/advanced/websupport/quickstart.rst

@@ -112,8 +112,8 @@ must update the websupport package's data::
 should be a boolean representing whether the user has moderation privileges.
 The default value for *moderator* is ``False``.
 
-An example `Flask <https://flask.palletsprojects.com/>`_ function that checks whether a
-user is logged in and then retrieves a document is::
+An example `Flask <https://flask.palletsprojects.com/>`_ function that checks
+whether a user is logged in and then retrieves a document is::
 
    from sphinxcontrib.websupport.errors import *
 
@@ -152,8 +152,8 @@ To use the search form built-in to the Sphinx sidebar, create a function to
 handle requests to the URL 'search' relative to the documentation root.  The
 user's search query will be in the GET parameters, with the key `q`.  Then use
 the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to
-retrieve search results. In `Flask <https://flask.palletsprojects.com/>`_ that would be
-like this::
+retrieve search results. In `Flask <https://flask.palletsprojects.com/>`_ that
+would be like this::
 
    @app.route('/search')
    def search():

doc/usage/extensions/napoleon.rst

@@ -267,14 +267,9 @@ Google style with types in docstrings::
    `Python 2/3 compatible annotations`_ aren't currently
    supported by Sphinx and won't show up in the docs.
 
-.. _PEP 484:
-   https://www.python.org/dev/peps/pep-0484/
-
-.. _PEP 526:
-    https://www.python.org/dev/peps/pep-0526/
-
-.. _Python 2/3 compatible annotations:
-   https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
+.. _PEP 484: https://www.python.org/dev/peps/pep-0484/
+.. _PEP 526: https://www.python.org/dev/peps/pep-0526/
+.. _Python 2/3 compatible annotations: https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
 
 
 Configuration

doc/usage/installation.rst

@@ -189,26 +189,37 @@ the ``--pre`` flag.
 Docker
 ------
 
-Docker images for Sphinx are published on the `Docker Hub <https://hub.docker.com/>`_. There are two kind of images:
+Docker images for Sphinx are published on the `Docker Hub`_.  There are two kind
+of images:
 
-- `sphinxdoc/sphinx <https://hub.docker.com/repository/docker/sphinxdoc/sphinx>`_
-- `sphinxdoc/sphinx-latexpdf <https://hub.docker.com/repository/docker/sphinxdoc/sphinx-latexpdf>`_
+- `sphinxdoc/sphinx`_
+- `sphinxdoc/sphinx-latexpdf`_
 
-Former one is used for standard usage of Sphinx, and latter one is mainly used for PDF builds using LaTeX.
-Please choose one for your purpose.
+.. _Docker Hub: https://hub.docker.com/
+.. _sphinxdoc/sphinx: https://hub.docker.com/repository/docker/sphinxdoc/sphinx
+.. _sphinxdoc/sphinx-latexpdf: https://hub.docker.com/repository/docker/sphinxdoc/sphinx-latexpdf>
+
+Former one is used for standard usage of Sphinx, and latter one is mainly used for
+PDF builds using LaTeX.  Please choose one for your purpose.
 
 .. note::
 
-   sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is very large (over 2GB!).
+   sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is very large
+   (over 2GB!).
 
 .. hint::
 
-   When using docker images, please use ``docker run`` command to invoke sphinx commands.  For example,
-   you can use following command to create a Sphinx project::
+   When using docker images, please use ``docker run`` command to invoke sphinx
+   commands.  For example, you can use following command to create a Sphinx
+   project:
+
+   .. code-block:: bash
 
       $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart
 
-   And you can following command this to build HTML document::
+   And you can following command this to build HTML document:
+
+   .. code-block:: bash
 
       $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html
 

doc/usage/theming.rst

@@ -248,7 +248,8 @@ These themes are:
 
 **scrolls**
   A more lightweight theme, based on `the Jinja documentation
-  <https://jinja.palletsprojects.com/>`_.  The following color options are available:
+  <https://jinja.palletsprojects.com/>`_.  The following color options are
+  available:
 
   - **headerbordercolor**
   - **subheadlinecolor**

utils/doclinter.py

@@ -41,7 +41,7 @@ def lint(path: str) -> int:
                 pass
             else:
                 spaces = LEADING_SPACES.match(line).group(1)
-                if len(spaces) < code_block_depth:
+                if len(spaces) <= code_block_depth:
                     in_code_block = False
         elif LONG_INTERPRETED_TEXT.match(line):
             pass