Standardise on a common directive for describing code snippets

doc/development/html_themes/index.rst

@@ -114,7 +114,7 @@ Theme configuration (``theme.conf``)
 The :file:`theme.conf` file is in INI format [1]_ (readable by the standard
 Python :mod:`configparser` module) and has the following structure:
 
-.. sourcecode:: ini
+.. code-block:: ini
 
     [theme]
     inherit = base theme

doc/latex.rst

@@ -429,14 +429,14 @@ Keys that don't need to be overridden unless in special cases are:
 ``'geometry'``
    "geometry" package inclusion, the default definition is:
 
-   .. code:: latex
+   .. code-block:: latex
 
       '\\usepackage{geometry}'
 
    with an additional ``[dvipdfm]`` for Japanese documents.
    The Sphinx LaTeX style file executes:
 
-   .. code:: latex
+   .. code-block:: latex
 
       \PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}
 

doc/usage/domains/index.rst

@@ -123,7 +123,7 @@ This is particularly useful for literate programming:
    .. py:function:: spam(eggs)
       :no-typesetting:
 
-   .. code::
+   .. code:: python
 
       def spam(eggs):
           pass

doc/usage/domains/python.rst

@@ -545,7 +545,7 @@ It is customary to put the opening bracket before the comma.
 Python 3.12 introduced *type parameters*, which are type variables
 declared directly  within the class or function definition:
 
-.. code:: python
+.. code-block:: python
 
    class AnimalList[AnimalT](list[AnimalT]):
       ...
@@ -555,7 +555,7 @@ declared directly  within the class or function definition:
 
 The corresponding reStructuredText documentation would be:
 
-.. code:: rst
+.. code-block:: rst
 
    .. py:class:: AnimalList[AnimalT]
 

doc/usage/extensions/intersphinx.rst

@@ -145,7 +145,7 @@ linking:
 
    Example:
 
-   .. code:: python
+   .. code-block:: python
 
       intersphinx_mapping = {'https://docs.python.org/': None}
 

doc/usage/restructuredtext/basics.rst

@@ -589,7 +589,7 @@ directive::
 
 will generate the following HTML output:
 
-.. code:: html
+.. code-block:: html
 
    <meta name="description" content="The Sphinx documentation builder">
    <meta name="keywords" content="Sphinx, documentation, builder">

doc/usage/restructuredtext/directives.rst

@@ -522,6 +522,7 @@ __ https://pygments.org/docs/lexers
 
 .. rst:directive:: .. code-block:: [language]
                    .. sourcecode:: [language]
+                   .. code:: [language]
 
    Example::
 
@@ -953,7 +954,7 @@ mainly contained in information units, such as the language reference.
       (this notation is also used below to describe what entries are created).
       Examples:
 
-      .. code:: rst
+      .. code-block:: rst
 
          .. index:: single: execution
                     single: execution; context
@@ -966,7 +967,7 @@ mainly contained in information units, such as the language reference.
       The pair of values must be separated by a semicolon.
       Example:
 
-      .. code:: rst
+      .. code-block:: rst
 
          .. index:: pair: loop; statement
 
@@ -976,7 +977,7 @@ mainly contained in information units, such as the language reference.
       All three values must be separated by a semicolon.
       Example:
 
-      .. code:: rst
+      .. code-block:: rst
 
          .. index:: triple: module; search; path
 
@@ -986,7 +987,7 @@ mainly contained in information units, such as the language reference.
       A shortcut to create an index entry that refers to another entry.
       Example:
 
-      .. code:: rst
+      .. code-block:: rst
 
          .. index:: see: entry; other