Merge branch 'admonition-icons' of https://github.com/chrisjsewell/sp…

…hinx into admonition-icons

.ruff.toml

@@ -373,6 +373,7 @@ select = [
 [lint.per-file-ignores]
 "doc/*" = [
     "ANN",  # documentation doesn't need annotations
+    "TCH001",  # documentation doesn't need type-checking blocks
 ]
 "doc/conf.py" = ["INP001", "W605"]
 "doc/development/tutorials/examples/*" = ["INP001"]

doc/_themes/sphinx13/static/sphinx13.css

@@ -381,6 +381,10 @@ aside.topic {
     background-color: #f8f8f8;
 }
 
+p.topic-title {
+    margin-top: 0;
+}
+
 table {
     border-collapse: collapse;
     margin: 0 -0.5em 0 -0.5em;

doc/conf.py

@@ -306,6 +306,9 @@ def build_redirects(app: Sphinx, exception: Exception | None) -> None:
         (('development', 'builders.html'), 'howtos/builders.html'),
         (('development', 'theming.html'), 'html_themes/index.html'),
         (('development', 'templating.html'), 'html_themes/templating.html'),
+        (('development', 'tutorials', 'helloworld.html'), 'extending_syntax.html'),
+        (('development', 'tutorials', 'todo.html'), 'extending_build.html'),
+        (('development', 'tutorials', 'recipe.html'), 'adding_domain.html'),
     ):
         path = app.outdir.joinpath(*page)
         if path.exists():

doc/development/tutorials/recipe.rst → doc/development/tutorials/adding_domain.rst

@@ -1,5 +1,7 @@
-Developing a "recipe" extension
-===============================
+.. _tutorial-adding-domain:
+
+Adding a reference domain
+=========================
 
 The objective of this tutorial is to illustrate roles, directives and domains.
 Once complete, we will be able to use this extension to describe a recipe and
@@ -41,7 +43,9 @@ For that, we will need to add the following elements to Sphinx:
 Prerequisites
 -------------
 
-We need the same setup as in :doc:`the previous extensions <todo>`. This time,
+We need the same setup as in
+:ref:`the previous extensions <tutorial-extend-build>`.
+This time,
 we will be putting out extension in a file called :file:`recipe.py`.
 
 Here is an example of the folder structure you might obtain:
@@ -77,7 +81,8 @@ The first thing to examine is the ``RecipeDirective`` directive:
    :linenos:
    :pyobject: RecipeDirective
 
-Unlike :doc:`helloworld` and :doc:`todo`, this directive doesn't derive from
+Unlike :ref:`tutorial-extending-syntax` and :ref:`tutorial-extend-build`,
+this directive doesn't derive from
 :class:`docutils.parsers.rst.Directive` and doesn't define a ``run`` method.
 Instead, it derives from :class:`sphinx.directives.ObjectDescription` and
 defines  ``handle_signature`` and ``add_target_and_index`` methods. This is
@@ -90,9 +95,10 @@ for this node.
 
 We also see that this directive defines ``has_content``, ``required_arguments``
 and ``option_spec``. Unlike the ``TodoDirective`` directive added in the
-:doc:`previous tutorial <todo>`, this directive takes a single argument, the
-recipe name, and an option, ``contains``, in addition to the nested
-reStructuredText in the body.
+:ref:`previous tutorial <tutorial-extend-build>`,
+this directive takes a single argument,
+the recipe name, and an option, ``contains``,
+in addition to the nested reStructuredText in the body.
 
 .. rubric:: The index classes
 
@@ -167,7 +173,8 @@ indices and our cross-referencing code use this feature.
 
 .. currentmodule:: sphinx.application
 
-:doc:`As always <todo>`, the ``setup`` function is a requirement and is used to
+:ref:`As always <tutorial-extend-build>`,
+the ``setup`` function is a requirement and is used to
 hook the various parts of our extension into Sphinx. Let's look at the
 ``setup`` function for this extension.
 
@@ -224,4 +231,7 @@ Further reading
 For more information, refer to the `docutils`_ documentation and
 :doc:`/extdev/index`.
 
+If you wish to share your extension across multiple projects or with others,
+check out the :ref:`third-party-extensions` section.
+
 .. _docutils: https://docutils.sourceforge.io/docs/

doc/development/tutorials/autodoc_ext.rst

@@ -1,7 +1,7 @@
 .. _autodoc_ext_tutorial:
 
-Developing autodoc extension for IntEnum
-========================================
+Developing autodoc extensions
+=============================
 
 The objective of this tutorial is to create an extension that adds
 support for new type for autodoc. This autodoc extension will format
@@ -27,8 +27,10 @@ We want to add following to autodoc:
 Prerequisites
 -------------
 
-We need the same setup as in :doc:`the previous extensions <todo>`. This time,
-we will be putting out extension in a file called :file:`autodoc_intenum.py`.
+We need the same setup as in
+:ref:`the previous extensions <tutorial-extend-build>`.
+This time, we will be putting out extension
+in a file called :file:`autodoc_intenum.py`.
 The :file:`my_enums.py` will contain the sample enums we will document.
 
 Here is an example of the folder structure you might obtain:
@@ -139,3 +141,9 @@ This will be the documentation file with auto-documentation directive:
    :caption: index.rst
 
    .. autointenum:: my_enums.Colors
+
+Further reading
+---------------
+
+If you wish to share your extension across multiple projects or with others,
+check out the :ref:`third-party-extensions` section.

doc/development/tutorials/examples/helloworld.py

@@ -1,18 +1,33 @@
+from __future__ import annotations
+
 from docutils import nodes
-from docutils.parsers.rst import Directive
 
 from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxDirective, SphinxRole
 from sphinx.util.typing import ExtensionMetadata
 
 
-class HelloWorld(Directive):
-    def run(self):
-        paragraph_node = nodes.paragraph(text='Hello World!')
+class HelloRole(SphinxRole):
+    """A role to say hello!"""
+
+    def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+        node = nodes.inline(text=f'Hello {self.text}!')
+        return [node], []
+
+
+class HelloDirective(SphinxDirective):
+    """A directive to say hello!"""
+
+    required_arguments = 1
+
+    def run(self) -> list[nodes.Node]:
+        paragraph_node = nodes.paragraph(text=f'hello {self.arguments[0]}!')
         return [paragraph_node]
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
-    app.add_directive('helloworld', HelloWorld)
+    app.add_role('hello', HelloRole())
+    app.add_directive('hello', HelloDirective)
 
     return {
         'version': '0.1',

doc/development/tutorials/todo.rst → doc/development/tutorials/extending_build.rst

@@ -1,14 +1,20 @@
-Developing a "TODO" extension
-=============================
+.. _tutorial-extend-build:
 
-The objective of this tutorial is to create a more comprehensive extension than
-that created in :doc:`helloworld`. Whereas that guide just covered writing a
-custom :term:`directive`, this guide adds multiple directives, along with custom
-nodes, additional config values and custom event handlers. To this end, we will
-cover a ``todo`` extension that adds capabilities to include todo entries in the
-documentation, and to collect these in a central place. This is similar the
-``sphinxext.todo`` extension distributed with Sphinx.
+Extending the build process
+===========================
 
+The objective of this tutorial is to create a more comprehensive extension than
+that created in :ref:`tutorial-extending-syntax`.
+Whereas that guide just covered writing
+a custom :term:`role` and :term:`directive`,
+this guide covers a more complex extension to the Sphinx build process;
+adding multiple directives,
+along with custom nodes, additional config values and custom event handlers.
+
+To this end, we will cover a ``todo`` extension
+that adds capabilities to include todo entries in the documentation,
+and to collect these in a central place.
+This is similar to the :mod:`sphinx.ext.todo` extension distributed with Sphinx.
 
 Overview
 --------
@@ -47,7 +53,8 @@ For that, we will need to add the following elements to Sphinx:
 Prerequisites
 -------------
 
-As with :doc:`helloworld`, we will not be distributing this plugin via PyPI so
+As with :ref:`tutorial-extending-syntax`,
+we will not be distributing this plugin via PyPI so
 once again we need a Sphinx project to call this from. You can use an existing
 project or create a new one using :program:`sphinx-quickstart`.
 
@@ -83,7 +90,8 @@ explain in detail shortly:
    :language: python
    :linenos:
 
-This is far more extensive extension than the one detailed in :doc:`helloworld`,
+This is far more extensive extension than the one detailed in
+:ref:`tutorial-extending-syntax`,
 however, we will will look at each piece step-by-step to explain what's
 happening.
 
@@ -250,7 +258,8 @@ ID as the anchor name.
 
 .. currentmodule:: sphinx.application
 
-As noted :doc:`previously <helloworld>`, the ``setup`` function is a requirement
+As noted :ref:`previously <tutorial-extending-syntax>`,
+the ``setup`` function is a requirement
 and is used to plug directives into Sphinx. However, we also use it to hook up
 the other parts of our extension. Let's look at our ``setup`` function:
 
@@ -361,6 +370,9 @@ Further reading
 For more information, refer to the `docutils`_ documentation and
 :doc:`/extdev/index`.
 
+If you wish to share your extension across multiple projects or with others,
+check out the :ref:`third-party-extensions` section.
+
 
 .. _docutils: https://docutils.sourceforge.io/docs/
 .. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH