✏️ Fix typo and reST syntax

veit · veit · commit 95142ef1445e · 2024-12-05T09:37:34.000+01:00
diff --git a/docs/control-flows/exceptions.rst b/docs/control-flows/exceptions.rst
@@ -92,9 +92,6 @@ Checks
 * If :class:`MyError` inherits from :class:`Exception`, what is the difference
   between ``except Exception as e`` and ``except MyError as e``?
 
-  The first catches every exception that inherits from :class:`Exception`, while
-  the second only catches :class:`MyError` exceptions.
-
 * Write a simple program that receives a number and then uses the :func:`assert`
   statement to throw an :class:`python3:Exception` if the number is ``0``.
 
diff --git a/docs/document/sphinx/uml/class-diagram.rst b/docs/document/sphinx/uml/class-diagram.rst
@@ -3,28 +3,29 @@ Class diagram
 
 
 ``abstract class``, ``abstract``
-
     Example:
 
     .. code-block:: rest
 
        .. uml::
 
-           abstract class  "Abstract class"
+          abstract class  "Abstract class"
 
     .. image:: abstract-class.svg
 
 ``annotation``
+    Example:
 
     .. code-block:: rest
 
        .. uml::
 
-           annotation      Annotation
+          annotation      Annotation
 
     .. image:: annotation.svg
 
 ``circle``, ``()``
+    Example:
 
     .. code-block:: rest
 
@@ -35,12 +36,13 @@ Class diagram
     .. image:: circle.svg
 
 ``class``
+    Example:
 
     .. code-block:: rest
 
        .. uml::
 
-           class           Class
+          class           Class
 
     .. image:: class.svg
 
@@ -52,21 +54,23 @@ Class diagram
 
        .. uml::
 
-           diamond         Association
+          diamond         Association
 
     .. image:: diamond.svg
 
 ``entity``
+    Example:
 
     .. code-block:: rest
 
        .. uml::
 
-           entity          Entity
+          entity          Entity
 
     .. image:: entity.svg
 
 ``enum``
+    Example:
 
     .. code-block:: rest
 
@@ -77,6 +81,7 @@ Class diagram
     .. image:: enum.svg
 
 ``interface``
+    Example:
 
     .. code-block:: rest
 
diff --git a/docs/document/sphinx/uml/index.rst b/docs/document/sphinx/uml/index.rst
@@ -18,10 +18,22 @@ Installation
 
          $ brew install plantuml
 
+   .. tab:: Windows
+
+      .. code-block:: ps1
+
+         $ choco install plantuml
+
 #. Install `sphinxcontrib-plantuml
    <https://pypi.org/project/sphinxcontrib-plantuml/>`_:
 
-   .. tab:: Linux/macOS
+   .. tab:: Linux
+
+      .. code-block:: console
+
+         $ python -m pip install sphinxcontrib-plantuml
+
+   .. tab:: macOS
 
       .. code-block:: console
 
diff --git a/docs/install.rst b/docs/install.rst
@@ -29,14 +29,6 @@ installed, this should not be a problem.
       One disadvantage is that you have to return to the website regularly to
       check for security updates as there is no integrated auto-updater.
 
-.. _various-python-versions:
-
-If different Python versions are required, for example to test libraries with
-:doc:`test/tox`, I use `uv <https://docs.astral.sh/uv/guides/install-python/>`_.
-This allows not only older CPython versions to be installed but also  `PyPy
-<https://pypy.org>`_ or free-threaded Python 3.13 with ``uv python install
-pypy@3.12`` or ``uv python install 3.13t``.
-
 .. tab:: macOS
 
    You can obtain Python directly from https://www.python.org/downloads/macos/.
@@ -79,6 +71,14 @@ pypy@3.12`` or ``uv python install 3.13t``.
          One disadvantage is that you have to return to the website regularly to
          check for security updates, as there is no integrated auto-updater.
 
+.. _various-python-versions:
+
+If different Python versions are required, for example to test libraries with
+:doc:`test/tox`, I use `uv <https://docs.astral.sh/uv/guides/install-python/>`_.
+This allows not only older CPython versions to be installed but also  `PyPy
+<https://pypy.org>`_ or free-threaded Python 3.13 with ``uv python install
+pypy@3.12`` or ``uv python install 3.13t``.
+
 .. tip::
    `direnv <https://direnv.net>`_ allows you to set environment variables
    depending on the directory. This allows you to install environment variables
diff --git a/docs/libs/batteries.rst b/docs/libs/batteries.rst
@@ -26,8 +26,9 @@ different data types: Modules for strings, datatypes and numbers.
 String modules
 ~~~~~~~~~~~~~~
 
-.. include:: ../types/strings.rst
-   :start-after: string-modules
+.. include:: ../types/strings/index.rst
+   :start-after: string-modules:
+   :end-before: end-string-modules:
 
 Modules for data types
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -61,15 +62,17 @@ Modules for numbers
 ~~~~~~~~~~~~~~~~~~~
 
 .. include:: ../types/numbers.rst
-   :start-after: number-modules
+   :start-after: number-modules:
+   :end-before: end-number-modules:
 
 .. _files-storage:
 
 Changing files
 --------------
 
 .. include:: ../types/files.rst
-   :start-after: file-modules
+   :start-after: file-modules:
+   :end-before: end-file-modules:
 
 .. _os:
 
diff --git a/docs/oop/design/command.rst b/docs/oop/design/command.rst
@@ -58,6 +58,7 @@ containing a list of functions for future calls, for example:
 .. literalinclude:: caller.py
    :language: python
    :linenos:
+   :emphasize-lines: 4-5, 7-8
 
 Lines 4–5
     creates a list from the command arguments and ensures that it is iterable.
diff --git a/docs/oop/design/strategy.rst b/docs/oop/design/strategy.rst
@@ -84,6 +84,7 @@ concrete strategies with simple functions and removing the abstract
    :language: python
    :linenos:
    :lines: 1-57
+   :emphasize-lines: 33, 40
 
 Line 33:
     To calculate a discount, simply call the function :func:`self.promotion`.
diff --git a/docs/oop/summary.rst b/docs/oop/summary.rst
@@ -6,94 +6,94 @@ will now summarise these basics in a single example:
 
 #. First, we create a base class:
 
-    .. literalinclude:: form.py
-        :language: python
-        :linenos:
-        :lines: 4-13
-        :lineno-start: 4
-
-    Line 7
-        The ``__init__`` method requires one instance (``self``) and two
-        parameters.
-    Lines 8 and 9
-        The two instance variables ``x`` and ``y``, which are accessed via
-        ``self``.
-    Line 11
-        The ``move`` method requires one instance (``self``) and two parameters.
-    Lines 12 and 13
-        Instance variables that are set in the ``move`` method.
+   .. literalinclude:: form.py
+      :language: python
+      :linenos:
+      :lines: 4-13
+      :lineno-start: 4
+
+   Line 7
+       The ``__init__`` method requires one instance (``self``) and two
+       parameters.
+   Lines 8 and 9
+       The two instance variables ``x`` and ``y``, which are accessed via
+       ``self``.
+   Line 11
+       The ``move`` method requires one instance (``self``) and two parameters.
+   Lines 12 and 13
+       Instance variables that are set in the ``move`` method.
 
 #. Next, create a subclass that inherits from the base class ``Form``:
 
-    .. literalinclude:: form.py
-        :language: python
-        :linenos:
-        :lines: 16-21
-        :lineno-start: 16
-
-    Line 16
-        The class ``Square`` inherits from the class ``Form``.
-    Line 19
-        ``Square``’s ``__init__`` takes one instance (``self``) and three
-        parameters, all with defaults.
-    Line 20
-        ``Circle``’s ``__init__`` uses ``super()`` to call ``Form``’s
-        ``__init__``.
+   .. literalinclude:: form.py
+      :language: python
+      :linenos:
+      :lines: 16-21
+      :lineno-start: 16
+
+   Line 16
+       The class ``Square`` inherits from the class ``Form``.
+   Line 19
+       ``Square``’s ``__init__`` takes one instance (``self``) and three
+       parameters, all with defaults.
+   Line 20
+       ``Circle``’s ``__init__`` uses ``super()`` to call ``Form``’s
+       ``__init__``.
 
 #. Finally, we create another subclass that also contains a static method:
 
-    .. literalinclude:: form.py
-        :language: python
-        :linenos:
-        :lines: 27-
-        :lineno-start: 27
-
-    Lines 30 and 31
-        ``pi`` and ``circles`` are class variables for ``Circle``.
-    Line 33
-        In the ``__init__`` method, the instance inserts itself into the
-        ``circles`` list.
-    Lines 38 and 39
-        ``circumferences`` is a class method and takes the class itself
-        (``cls``) as a parameter.
-    Line 42
-        uses the parameter ``cls`` to access the class variable ``circles``.
+   .. literalinclude:: form.py
+      :language: python
+      :linenos:
+      :lines: 27-
+      :lineno-start: 27
+
+   Lines 30 and 31
+       ``pi`` and ``circles`` are class variables for ``Circle``.
+   Line 33
+       In the ``__init__`` method, the instance inserts itself into the
+       ``circles`` list.
+   Lines 38 and 39
+       ``circumferences`` is a class method and takes the class itself
+       (``cls``) as a parameter.
+   Line 42
+       uses the parameter ``cls`` to access the class variable ``circles``.
 
 Now you can create some instances of the class ``Circle`` and analyse them.
 Since the ``__init__`` method of ``Circle`` has default parameters, you can
 create a circle without specifying any parameters:
 
-    .. code-block:: pycon
+.. code-block:: pycon
 
-        >>> import form
-        >>> c1 = form.Circle()
-        >>> c1.diameter, c1.x, c1.y
-        (1, 0, 0)
+   >>> import form
+   >>> c1 = form.Circle()
+   >>> c1.diameter, c1.x, c1.y
+   (1, 0, 0)
 
 If you specify parameters, they are used to set the values of the instance:
 
-    .. code-block:: pycon
+.. code-block:: pycon
 
-        >>> c2 = form.Circle(2, 3, 4)
-        >>> c2.diameter, c2.x, c2.y
-        (2, 3, 4)
+   >>> c2 = form.Circle(2, 3, 4)
+   >>> c2.diameter, c2.x, c2.y
+   (2, 3, 4)
 
 When you call the ``move()`` method, Python does not find a ``move()`` method in
 the ``Circle`` class, so it goes up the inheritance hierarchy and uses the
 ``move()`` method of ``Form``:
 
-    .. code-block:: pycon
+.. code-block:: pycon
 
-        >>> c2.move(5, 6)
-        >>> c2.diameter, c2.x, c2.y
-        (2, 8, 10)
+   >>> c2.move(5, 6)
+   >>> c2.diameter, c2.x, c2.y
+   (2, 8, 10)
 
 You can also call the class method ``circumferences()`` of the class ``Circle``,
 either through the class itself or through an instance:
 
-    .. code-block:: pycon
+.. code-block:: pycon
 
-        >>> form.Circle.circumferences()
-        9.424769999999999
-        >>> c2.circumferences()
-        9.424769999999999
+   >>> form.Circle.circumferences()
+   9.424769999999999
+   >>> c2.circumferences()
+   9.424769999999999
diff --git a/docs/test/pytest/markers.rst b/docs/test/pytest/markers.rst
@@ -753,7 +753,7 @@ have. This requires three steps:
 
    .. code-block:: python
       :linenos:
-      :emphasize-lines: 5, 13-
+      :emphasize-lines: 5, 12-
 
       import os
       from pathlib import Path
@@ -787,22 +787,22 @@ have. This requires three steps:
    Line 13
     We have added ``request`` and ``faker`` to the list of ``items_db``
     parameters.
-   Line 17
+   Line 18
     This sets the randomness of faker so that we get the same data every time.
     We are not using faker here for very random data, but to avoid having to
     invent data ourselves.
-   Line 18
+   Line 19
     Here we use ``request``, more precisely ``request.node`` for the pytest
     representation of a test. ``get_closest_marker('num_items')`` returns a
     marker object if the test is marked with ``num_items``, otherwise it returns
     ``None``. The :func:`get_closest_marker` function returns the marker closest
     t545o the test, which is usually what we want.
-   Line 19
+   Line 20
     The expression is true if the test is marked with ``num_items`` and an
     argument is given. The additional ``len`` check is there so that if someone
     accidentally just uses ``pytest.mark.num_items`` without specifying the
     number of items, this part is skipped.
-   Line 20–22
+   Line 22–24
     Once we know how many items we need to create, we let Faker create some data
     for us. Faker provides the Faker fixture.
 
diff --git a/docs/types/files.rst b/docs/types/files.rst
@@ -299,6 +299,7 @@ use to manage files:
 | :py:mod:`tarfile`                 |                                                                               |
 +-----------------------------------+-------------------------------------------------------------------------------+
 
+.. _end-file-modules:
 
 .. seealso::
    * :doc:`Python4DataScience:data-processing/pandas-io`
diff --git a/docs/types/numbers.rst b/docs/types/numbers.rst
diff --git a/docs/types/sets.rst b/docs/types/sets.rst
diff --git a/docs/types/strings/index.rst b/docs/types/strings/index.rst
