diff --git a/doc/development/theming.rst b/doc/development/theming.rst
index 5de10158ae4..da2c644b9c6 100644
--- a/doc/development/theming.rst
+++ b/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::
diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst
index ae81fc5628f..7c331382c65 100644
--- a/doc/extdev/appapi.rst
+++ b/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,7 +170,7 @@ 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
@@ -176,10 +178,10 @@ type for that event::
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
diff --git a/doc/faq.rst b/doc/faq.rst
index 93486db7510..4b273023d3a 100644
--- a/doc/faq.rst
+++ b/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.
diff --git a/doc/usage/advanced/websupport/quickstart.rst b/doc/usage/advanced/websupport/quickstart.rst
index 1c7e7cd35d9..5fa5b00f14c 100644
--- a/doc/usage/advanced/websupport/quickstart.rst
+++ b/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 `_ function that checks whether a
-user is logged in and then retrieves a document is::
+An example `Flask `_ 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 `_ that would be
-like this::
+retrieve search results. In `Flask `_ that
+would be like this::
@app.route('/search')
def search():
diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst
index 2752b1479b1..3f044d6e637 100644
--- a/doc/usage/extensions/napoleon.rst
+++ b/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
diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst
index f0384ea9dda..49681f2ba96 100644
--- a/doc/usage/installation.rst
+++ b/doc/usage/installation.rst
@@ -189,26 +189,37 @@ the ``--pre`` flag.
Docker
------
-Docker images for Sphinx are published on the `Docker Hub `_. There are two kind of images:
+Docker images for Sphinx are published on the `Docker Hub`_. There are two kind
+of images:
-- `sphinxdoc/sphinx `_
-- `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
diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst
index 8ea574cfd24..60bc20e24fb 100644
--- a/doc/usage/theming.rst
+++ b/doc/usage/theming.rst
@@ -248,7 +248,8 @@ These themes are:
**scrolls**
A more lightweight theme, based on `the Jinja documentation
- `_. The following color options are available:
+ `_. The following color options are
+ available:
- **headerbordercolor**
- **subheadlinecolor**
diff --git a/utils/doclinter.py b/utils/doclinter.py
index f8df20bf7f8..6299fe46acf 100644
--- a/utils/doclinter.py
+++ b/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