Merge branch '4.x' into new-tutorial

5 files changed, 31 insertions, 24 deletions

diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst
index 976b26727..3bf353e8d 100644
--- a/doc/usage/advanced/intl.rst
+++ b/doc/usage/advanced/intl.rst
@@ -118,7 +118,7 @@ section describe an easy way to translate with *sphinx-intl*.
 
 #. Translate po files.
 
-   AS noted above, these are located in the ``./locale/<lang>/LC_MESSAGES``
+   As noted above, these are located in the ``./locale/<lang>/LC_MESSAGES``
    directory.  An example of one such file, from Sphinx, ``builders.po``, is
    given below.
 
@@ -193,7 +193,7 @@ pot file to the po file, use the :command:`sphinx-intl update` command.
 
 .. code-block:: console
 
-   $ sphinx-intl update -p _build/locale
+   $ sphinx-intl update -p _build/gettext
 
 
 Using Transifex service for team translation
diff --git a/doc/usage/advanced/websupport/quickstart.rst b/doc/usage/advanced/websupport/quickstart.rst
index 1c7e7cd35..5fa5b00f1 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 <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():
diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst
index 2752b1479..3f044d6e6 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 249b9a095..8cf56b501 100644
--- a/doc/usage/installation.rst
+++ b/doc/usage/installation.rst
@@ -215,26 +215,37 @@ You can read more about them in the `Python Packaging User Guide`_.
 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
 
diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst
index 8ea574cfd..60bc20e24 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
-  <https://jinja.palletsprojects.com/>`_.  The following color options are available:
+  <https://jinja.palletsprojects.com/>`_.  The following color options are
+  available:
 
   - **headerbordercolor**
   - **subheadlinecolor**