From 7b570c06a16036285906d9bfa1b287db579e4686 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sun, 14 Jul 2024 06:06:07 +0100
Subject: [PATCH] Standardise on a common directive for describing code
 snippets

---
 doc/development/html_themes/index.rst     | 2 +-
 doc/latex.rst                             | 4 ++--
 doc/usage/domains/index.rst               | 2 +-
 doc/usage/domains/python.rst              | 4 ++--
 doc/usage/extensions/intersphinx.rst      | 2 +-
 doc/usage/restructuredtext/basics.rst     | 2 +-
 doc/usage/restructuredtext/directives.rst | 9 +++++----
 7 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/doc/development/html_themes/index.rst b/doc/development/html_themes/index.rst
index 31d6cfdfd..8724398a5 100644
--- a/doc/development/html_themes/index.rst
+++ b/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
diff --git a/doc/latex.rst b/doc/latex.rst
index d6855021c..98081765c 100644
--- a/doc/latex.rst
+++ b/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}
 
diff --git a/doc/usage/domains/index.rst b/doc/usage/domains/index.rst
index 643ecf534..8c4713415 100644
--- a/doc/usage/domains/index.rst
+++ b/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
diff --git a/doc/usage/domains/python.rst b/doc/usage/domains/python.rst
index 6777b76d0..5b98baa78 100644
--- a/doc/usage/domains/python.rst
+++ b/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]
 
diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst
index 9f67e37e4..f64b59680 100644
--- a/doc/usage/extensions/intersphinx.rst
+++ b/doc/usage/extensions/intersphinx.rst
@@ -145,7 +145,7 @@ linking:
 
    Example:
 
-   .. code:: python
+   .. code-block:: python
 
       intersphinx_mapping = {'https://docs.python.org/': None}
 
diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst
index f63ef7d75..53547486a 100644
--- a/doc/usage/restructuredtext/basics.rst
+++ b/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">
diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst
index c73d7d070..72df2d5d3 100644
--- a/doc/usage/restructuredtext/directives.rst
+++ b/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