🎨 Fix reST syntax

Author: veit

docs/document/sphinx/docstrings.rst

@@ -21,7 +21,7 @@ file  ``docs/conf.py``:
 
 .. code-block:: python
 
-    extensions = ["sphinx.ext.autodoc", ...]
+   extensions = ["sphinx.ext.autodoc", ...]
 
 If your package and its documentation are part of the same repository, they will
 always have the same relative position in the filesystem. In this case you can
@@ -30,21 +30,21 @@ path to the package, so:
 
 .. code-block:: python
 
-    sys.path.insert(0, os.path.abspath(".."))
-    import requests
+   sys.path.insert(0, os.path.abspath(".."))
+   import requests
 
 If you have installed your Sphinx documentation in a virtual environment, you
 can also install your package there with:
 
 .. code-block:: console
 
-    $ python -m pip install my.package
+   $ python -m pip install my.package
 
 or, if you want to develop the package further with:
 
 .. code-block:: console
 
-    $ python -m pip install -e https://github.com/veit/my.package.git
+   $ python -m pip install -e https://github.com/veit/my.package.git
 
 Examples
 --------
@@ -73,42 +73,40 @@ The variant with types according to :pep:`484` has the advantage that type
 testers and IDEs can be used for static code analysis.
 
 Python 3 type annotations:
-
     .. code-block:: python
 
-        def func(arg1: int, arg2: str) -> bool:
-            """Summary line.
+       def func(arg1: int, arg2: str) -> bool:
+           """Summary line.
 
-            Extended description of function.
+           Extended description of function.
 
-            Args:
-                arg1: Description of arg1
-                arg2: Description of arg2
+           Args:
+               arg1: Description of arg1
+               arg2: Description of arg2
 
-            Returns:
-                Description of return value
+           Returns:
+               Description of return value
 
-            """
-            return True
+           """
+           return True
 
 Types in Docstrings:
-
     .. code-block:: python
 
-        def func(arg1, arg2):
-            """Summary line.
+       def func(arg1, arg2):
+           """Summary line.
 
-            Extended description of function.
+           Extended description of function.
 
-            Args:
-                arg1 (int): Description of arg1
-                arg2 (str): Description of arg2
+           Args:
+               arg1 (int): Description of arg1
+               arg2 (str): Description of arg2
 
-            Returns:
-                bool: Description of return value
+           Returns:
+               bool: Description of return value
 
-            """
-            return True
+           """
+           return True
 
 .. note::
    :pep:`484#suggested-syntax-for-python-2-7-and-straddling-code` are currently
@@ -140,47 +138,45 @@ The main differences are that Google uses indentations and NumPy uses
 underscores:
 
 Google:
-
     .. code-block:: python
 
-        def func(arg1, arg2):
-            """Summary line.
+       def func(arg1, arg2):
+           """Summary line.
 
-            Extended description of function.
+           Extended description of function.
 
-            Args:
-                arg1 (int): Description of arg1
-                arg2 (str): Description of arg2
+           Args:
+               arg1 (int): Description of arg1
+               arg2 (str): Description of arg2
 
-            Returns:
-                bool: Description of return value
+           Returns:
+               bool: Description of return value
 
-            """
-            return True
+           """
+           return True
 
 NumPy:
-
     .. code-block:: python
 
-        def func(arg1, arg2):
-            """Summary line.
+       def func(arg1, arg2):
+           """Summary line.
 
-            Extended description of function.
+           Extended description of function.
 
-            Parameters
-            ----------
-            arg1 : int
-                Description of arg1
-            arg2 : str
-                Description of arg2
+           Parameters
+           ----------
+           arg1 : int
+               Description of arg1
+           arg2 : str
+               Description of arg2
 
-            Returns
-            -------
-            bool
-                Description of return value
+           Returns
+           -------
+           bool
+               Description of return value
 
-            """
-            return True
+           """
+           return True
 
 You can find the detailed configuration options in
 `sphinxcontrib.napoleon.Config

docs/document/sphinx/intersphinx.rst

@@ -12,26 +12,26 @@ In ``docs/conf.py`` Intersphinx must be indicated as an extension:
 
 .. code-block:: python
 
-    extensions = [
-        "sphinx.ext.intersphinx",
-    ]
+   extensions = [
+       "sphinx.ext.intersphinx",
+   ]
 
 External Sphinx documentation can then be specified, e.g. with:
 
 .. code-block:: python
 
-    intersphinx_mapping = {
-        "python": ("https://docs.python.org/3", None),
-        "bokeh": ("https://bokeh.pydata.org/en/latest/", None),
-    }
+   intersphinx_mapping = {
+       "python": ("https://docs.python.org/3", None),
+       "bokeh": ("https://bokeh.pydata.org/en/latest/", None),
+   }
 
 However, alternative files can also be specified for an inventory, for example:
 
 .. code-block:: python
 
-    intersphinx_mapping = {
-        "python": ("https://docs.python.org/3", None, "python-inv.txt"),
-    }
+   intersphinx_mapping = {
+       "python": ("https://docs.python.org/3", None, "python-inv.txt"),
+   }
 
 Determine link targets
 ----------------------
@@ -41,12 +41,12 @@ for example:
 
 .. code-block:: console
 
-    $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
-    c:function
-        PyAnySet_Check                           c-api/set.html#c.PyAnySet_Check
-        PyAnySet_CheckExact                      c-api/set.html#c.PyAnySet_CheckExact
-        PyArg_Parse                              c-api/arg.html#c.PyArg_Parse
-    …
+   $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
+   c:function
+       PyAnySet_Check                           c-api/set.html#c.PyAnySet_Check
+       PyAnySet_CheckExact                      c-api/set.html#c.PyAnySet_CheckExact
+       PyArg_Parse                              c-api/arg.html#c.PyArg_Parse
+   …
 
 Create a link
 -------------
@@ -57,17 +57,17 @@ of the following variants can be specified:
 :c:func:`PyArg_Parse`
     .. code-block:: rest
 
-        :c:func:`PyArg_Parse`
+       :c:func:`PyArg_Parse`
 
 :c:func:`!PyArg_Parse`
     .. code-block:: rest
 
-        :c:func:`!PyArg_Parse`
+       :c:func:`!PyArg_Parse`
 
 :c:func:`Parsing arguments <PyArg_Parse>`
     .. code-block:: rest
 
-        :c:func:`Parsing arguments <PyArg_Parse>`
+       :c:func:`Parsing arguments <PyArg_Parse>`
 
 Custom links
 ------------
@@ -82,50 +82,48 @@ The error can be corrected with:
 
    .. code-block:: console
 
-    $ python -m pip install sphobjinv
+      $ python -m pip install sphobjinv
 
 #. Then the original file can be downloaded with:
 
    .. code-block:: console
 
-    $ cd docs/build/
-    $ mkdir _intersphinx
-    $ !$
-    $ curl -O https://www.crummy.com/software/BeautifulSoup/bs4/doc/objects.inv
-    $ mv objects.inv bs4_objects.inv
+      $ cd docs/build/
+      $ mkdir _intersphinx
+      $ !$
+      $ curl -O https://www.crummy.com/software/BeautifulSoup/bs4/doc/objects.inv
+      $ mv objects.inv bs4_objects.inv
 
 #. Change the Sphinx configuration ``docs/conf.py``:
 
    .. code-block:: console
 
-    intersphinx_mapping = {
-        …
-        'bs4':    ('https://www.crummy.com/software/BeautifulSoup/bs4/doc/', "_intersphinx/bs4_objects.inv")
+      intersphinx_mapping = {
+          …
+          'bs4':    ('https://www.crummy.com/software/BeautifulSoup/bs4/doc/', "_intersphinx/bs4_objects.inv")
     }
 
 #. Convert to a text file:
 
    .. code-block:: console
 
-    $ sphobjinv convert plain bs4_objects.inv bs4_objects.txt
+      $ sphobjinv convert plain bs4_objects.inv bs4_objects.txt
 
 #. Editing the text file
 
-   e.g.:
-
    .. code-block:: console
 
-    bs4.BeautifulSoup           py:class  1 index.html#beautifulsoup -
-    bs4.BeautifulSoup.get_text  py:method 1 index.html#get-text      -
-    bs4.element.Tag             py:class  1 index.html#tag           -
+      bs4.BeautifulSoup           py:class  1 index.html#beautifulsoup -
+      bs4.BeautifulSoup.get_text  py:method 1 index.html#get-text      -
+      bs4.element.Tag             py:class  1 index.html#tag           -
 
    These entries can then be referenced in a Sphinx documentation with:
 
    .. code-block:: rest
 
-    - :class:`bs4.BeautifulSoup`
-    - :meth:`bs4.BeautifulSoup.get_text`
-    - :class:`bs4.element.Tag`
+      - :class:`bs4.BeautifulSoup`
+      - :meth:`bs4.BeautifulSoup.get_text`
+      - :class:`bs4.element.Tag`
 
    .. seealso::
       * `Sphinx objects.inv v2 Syntax
@@ -135,13 +133,13 @@ The error can be corrected with:
 
    .. code-block:: console
 
-        $ sphobjinv convert zlib bs4_objects.txt bs4_objects.txt
+      $ sphobjinv convert zlib bs4_objects.txt bs4_objects.txt
 
 #. Create Sphinx documentation:
 
    .. code-block:: console
 
-        $ python -m sphinx -ab html docs/ docs/_build/
+      $ python -m sphinx -ab html docs/ docs/_build/
 
 Add roles
 ---------
@@ -150,18 +148,18 @@ If you get an error message that a certain text role is unknown, e.g.
 
 .. code-block:: console
 
-    WARNING: Unknown interpreted text role "confval".
+   WARNING: Unknown interpreted text role "confval".
 
 so you can add them in the ``conf.py``:
 
 .. code-block:: python
 
-    def setup(app):
-        # from sphinx.ext.autodoc import cut_lines
-        # app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
-        app.add_object_type(
-            "confval",
-            "confval",
-            objname="configuration value",
-            indextemplate="pair: %s; configuration value",
-        )
+   def setup(app):
+       # from sphinx.ext.autodoc import cut_lines
+       # app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
+       app.add_object_type(
+           "confval",
+           "confval",
+           objname="configuration value",
+           indextemplate="pair: %s; configuration value",
+       )

docs/document/sphinx/placeholder.rst

@@ -31,7 +31,7 @@ version.
    As of Sphinx≥1.8, curly braces can be displayed with a backslash (``\``).
 
 .. note::
-    .. rst:role:: content
+   .. rst:role:: content
 
    This role has no special meaning by default. You can therefore use it for
    anything, for example also for variable names.