summaryrefslogtreecommitdiffstats
path: root/doc/development
diff options
context:
space:
mode:
Diffstat (limited to 'doc/development')
-rw-r--r--doc/development/howtos/builders.rst (renamed from doc/development/builders.rst)0
-rw-r--r--doc/development/howtos/index.rst8
-rw-r--r--doc/development/howtos/setup_extension.rst (renamed from doc/development/overview.rst)13
-rw-r--r--doc/development/html_themes/index.rst (renamed from doc/development/theming.rst)37
-rw-r--r--doc/development/html_themes/templating.rst (renamed from doc/development/templating.rst)8
-rw-r--r--doc/development/index.rst29
-rw-r--r--doc/development/tutorials/adding_domain.rst (renamed from doc/development/tutorials/recipe.rst)26
-rw-r--r--doc/development/tutorials/autodoc_ext.rst16
-rw-r--r--doc/development/tutorials/examples/autodoc_intenum.py7
-rw-r--r--doc/development/tutorials/examples/helloworld.py25
-rw-r--r--doc/development/tutorials/examples/recipe.py1
-rw-r--r--doc/development/tutorials/examples/todo.py3
-rw-r--r--doc/development/tutorials/extending_build.rst (renamed from doc/development/tutorials/todo.rst)36
-rw-r--r--doc/development/tutorials/extending_syntax.rst223
-rw-r--r--doc/development/tutorials/helloworld.rst189
-rw-r--r--doc/development/tutorials/index.rst17
16 files changed, 370 insertions, 268 deletions
diff --git a/doc/development/builders.rst b/doc/development/howtos/builders.rst
index 7792fbd..7792fbd 100644
--- a/doc/development/builders.rst
+++ b/doc/development/howtos/builders.rst
diff --git a/doc/development/howtos/index.rst b/doc/development/howtos/index.rst
new file mode 100644
index 0000000..9800655
--- /dev/null
+++ b/doc/development/howtos/index.rst
@@ -0,0 +1,8 @@
+How-tos
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ setup_extension
+ builders
diff --git a/doc/development/overview.rst b/doc/development/howtos/setup_extension.rst
index df8f5bb..bcb4daf 100644
--- a/doc/development/overview.rst
+++ b/doc/development/howtos/setup_extension.rst
@@ -1,10 +1,5 @@
-Developing extensions overview
-==============================
-
-This page contains general information about developing Sphinx extensions.
-
-Make an extension depend on another extension
----------------------------------------------
+Depend on another extension
+===========================
Sometimes your extension depends on the functionality of another
Sphinx extension. Most Sphinx extensions are activated in a
@@ -19,12 +14,12 @@ use the :meth:`sphinx.application.Sphinx.setup_extension` method. This will
activate another extension at run-time, ensuring that you have access to its
functionality.
-For example, the following code activates the ``recommonmark`` extension:
+For example, the following code activates the :mod:`sphinx.ext.autodoc` extension:
.. code-block:: python
def setup(app):
- app.setup_extension("recommonmark")
+ app.setup_extension('sphinx.ext.autodoc')
.. note::
diff --git a/doc/development/theming.rst b/doc/development/html_themes/index.rst
index 13a5802..8724398 100644
--- a/doc/development/theming.rst
+++ b/doc/development/html_themes/index.rst
@@ -1,3 +1,5 @@
+.. _extension-html-theme:
+
HTML theme development
======================
@@ -112,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
@@ -222,6 +224,11 @@ If your theme package contains two or more themes, please call
Templating
----------
+.. toctree::
+ :hidden:
+
+ templating
+
The :doc:`guide to templating <templating>` is helpful if you want to write your
own templates. What is important to keep in mind is the order in which Sphinx
searches for templates:
@@ -247,12 +254,28 @@ template static files as well as HTML files. Therefore, Sphinx supports
so-called "static templates", like this:
If the name of a file in the ``static/`` directory of a theme (or in the user's
-static path, for that matter) ends with ``_t``, it will be processed by the
-template engine. The ``_t`` will be left from the final file name. For
-example, the *classic* theme has a file ``static/classic.css_t`` which uses
-templating to put the color options into the stylesheet. When a documentation
-project is built with the classic theme, the output directory will contain a
-``_static/classic.css`` file where all template tags have been processed.
+static path) ends with ``.jinja`` or ``_t``, it will be processed by the
+template engine. The suffix will be removed from the final file name.
+
+For example, a theme with a ``static/theme_styles.css.jinja`` file could use
+templating to put options into the stylesheet.
+When a documentation project is built with that theme,
+the output directory will contain a ``_static/theme_styles.css`` file
+where all template tags have been processed.
+
+.. versionchanged:: 7.4
+
+ The preferred suffix for static templates is now ``.jinja``, in line with
+ the Jinja project's `recommended file extension`_.
+
+ The ``_t`` file suffix for static templates is now considered 'legacy', and
+ support may eventually be removed.
+
+ If a static template with either a ``_t`` suffix or a ``.jinja`` suffix is
+ detected, it will be processed by the template engine, with the suffix
+ removed from the final file name.
+
+ .. _recommended file extension: https://jinja.palletsprojects.com/en/latest/templates/#template-file-extension
Use custom page metadata in HTML templates
diff --git a/doc/development/templating.rst b/doc/development/html_themes/templating.rst
index 016b8b8..e2de045 100644
--- a/doc/development/templating.rst
+++ b/doc/development/html_themes/templating.rst
@@ -289,8 +289,8 @@ in the future.
.. data:: has_source
- True if the reST document sources are copied (if :confval:`html_copy_source`
- is ``True``).
+ True if the reStructuredText document sources are copied
+ (if :confval:`html_copy_source` is ``True``).
.. data:: language
@@ -326,8 +326,8 @@ in the future.
.. data:: pagename
The "page name" of the current file, i.e. either the document name if the
- file is generated from a reST source, or the equivalent hierarchical name
- relative to the output directory
+ file is generated from a reStructuredText source,
+ or the equivalent hierarchical name relative to the output directory
(``[directory/]filename_without_extension``).
.. data:: project
diff --git a/doc/development/index.rst b/doc/development/index.rst
index 55a31a0..b059569 100644
--- a/doc/development/index.rst
+++ b/doc/development/index.rst
@@ -1,24 +1,19 @@
-=========================
-Writing Sphinx Extensions
-=========================
+.. _extending-sphinx:
+
+Extending Sphinx
+================
This guide is aimed at giving a quick introduction for those wishing to
-develop their own extensions for Sphinx. Sphinx possesses significant
-extensibility capabilities including the ability to hook into almost every
-point of the build process. If you simply wish to use Sphinx with existing
-extensions, refer to :doc:`/usage/index`. For a more detailed discussion of
-the extension interface see :doc:`/extdev/index`.
+develop their own extensions for Sphinx.
+Sphinx possesses significant extensibility capabilities
+including the ability to hook into almost every point of the build process.
+If you simply wish to use Sphinx with existing extensions,
+refer to :doc:`/usage/index`.
+For a more detailed discussion of the extension interface see :doc:`/extdev/index`.
.. toctree::
:maxdepth: 2
- overview
tutorials/index
- builders
-
-.. toctree::
- :caption: Theming
- :maxdepth: 2
-
- templating
- theming
+ howtos/index
+ html_themes/index
diff --git a/doc/development/tutorials/recipe.rst b/doc/development/tutorials/adding_domain.rst
index 683cc8c..8a00211 100644
--- a/doc/development/tutorials/recipe.rst
+++ b/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/
diff --git a/doc/development/tutorials/autodoc_ext.rst b/doc/development/tutorials/autodoc_ext.rst
index cfd23e7..fb2a917 100644
--- a/doc/development/tutorials/autodoc_ext.rst
+++ b/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.
diff --git a/doc/development/tutorials/examples/autodoc_intenum.py b/doc/development/tutorials/examples/autodoc_intenum.py
index c52bb4c..7a19a23 100644
--- a/doc/development/tutorials/examples/autodoc_intenum.py
+++ b/doc/development/tutorials/examples/autodoc_intenum.py
@@ -9,6 +9,7 @@ if TYPE_CHECKING:
from docutils.statemachine import StringList
from sphinx.application import Sphinx
+ from sphinx.util.typing import ExtensionMetadata
class IntEnumDocumenter(ClassDocumenter):
@@ -52,6 +53,10 @@ class IntEnumDocumenter(ClassDocumenter):
self.add_line('', source_name)
-def setup(app: Sphinx) -> None:
+def setup(app: Sphinx) -> ExtensionMetadata:
app.setup_extension('sphinx.ext.autodoc') # Require autodoc extension
app.add_autodocumenter(IntEnumDocumenter)
+ return {
+ 'version': '1',
+ 'parallel_read_safe': True,
+ }
diff --git a/doc/development/tutorials/examples/helloworld.py b/doc/development/tutorials/examples/helloworld.py
index da29562..3f7e504 100644
--- a/doc/development/tutorials/examples/helloworld.py
+++ b/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',
diff --git a/doc/development/tutorials/examples/recipe.py b/doc/development/tutorials/examples/recipe.py
index 28d25f2..baf85fe 100644
--- a/doc/development/tutorials/examples/recipe.py
+++ b/doc/development/tutorials/examples/recipe.py
@@ -122,6 +122,7 @@ class RecipeDomain(Domain):
'recipes': [], # object list
'recipe_ingredients': {}, # name -> object
}
+ data_version = 0
def get_full_qualified_name(self, node):
return f'recipe.{node.arguments[0]}'
diff --git a/doc/development/tutorials/examples/todo.py b/doc/development/tutorials/examples/todo.py
index 2baac5c..4e9dc66 100644
--- a/doc/development/tutorials/examples/todo.py
+++ b/doc/development/tutorials/examples/todo.py
@@ -38,7 +38,7 @@ class TodoDirective(SphinxDirective):
todo_node = todo('\n'.join(self.content))
todo_node += nodes.title(_('Todo'), _('Todo'))
- self.state.nested_parse(self.content, self.content_offset, todo_node)
+ todo_node += self.parse_content_to_nodes()
if not hasattr(self.env, 'todo_all_todos'):
self.env.todo_all_todos = []
@@ -132,6 +132,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
return {
'version': '0.1',
+ 'env_version': 1,
'parallel_read_safe': True,
'parallel_write_safe': True,
}
diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/extending_build.rst
index f23d8ad..a81c84b 100644
--- a/doc/development/tutorials/todo.rst
+++ b/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
diff --git a/doc/development/tutorials/extending_syntax.rst b/doc/development/tutorials/extending_syntax.rst
new file mode 100644
index 0000000..bab8037
--- /dev/null
+++ b/doc/development/tutorials/extending_syntax.rst
@@ -0,0 +1,223 @@
+.. _tutorial-extending-syntax:
+
+Extending syntax with roles and directives
+==========================================
+
+Overview
+--------
+
+The syntax of both reStructuredText and MyST can be extended
+by creating new **directives** - for block-level elements -
+and **roles** - for inline elements.
+
+In this tutorial we shall extend Sphinx to add:
+
+* A ``hello`` role, that will simply output the text ``Hello {text}!``.
+* A ``hello`` directive, that will simply output the text ``Hello {text}!``,
+ as a paragraph.
+
+For this extension, you will need some basic understanding of Python,
+and we shall also introduce aspects of the docutils_ API.
+
+Setting up the project
+----------------------
+
+You can either use an existing Sphinx project
+or create a new one using :program:`sphinx-quickstart`.
+
+With this we will add the extension to the project,
+within the :file:`source` folder:
+
+#. Create an :file:`_ext` folder in :file:`source`
+#. Create a new Python file in the :file:`_ext` folder called
+ :file:`helloworld.py`
+
+Here is an example of the folder structure you might obtain:
+
+.. code-block:: text
+
+ └── source
+    ├── _ext
+ │   └── helloworld.py
+    ├── conf.py
+    ├── index.rst
+
+
+Writing the extension
+---------------------
+
+Open :file:`helloworld.py` and paste the following code in it:
+
+.. literalinclude:: examples/helloworld.py
+ :language: python
+ :linenos:
+
+Some essential things are happening in this example:
+
+The role class
+...............
+
+Our new role is declared in the ``HelloRole`` class.
+
+.. literalinclude:: examples/helloworld.py
+ :language: python
+ :linenos:
+ :pyobject: HelloRole
+
+This class extends the :class:`.SphinxRole` class.
+The class contains a ``run`` method,
+which is a requirement for every role.
+It contains the main logic of the role and it
+returns a tuple containing:
+
+- a list of inline-level docutils nodes to be processed by Sphinx.
+- an (optional) list of system message nodes
+
+The directive class
+...................
+
+Our new directive is declared in the ``HelloDirective`` class.
+
+.. literalinclude:: examples/helloworld.py
+ :language: python
+ :linenos:
+ :pyobject: HelloDirective
+
+This class extends the :class:`.SphinxDirective` class.
+The class contains a ``run`` method,
+which is a requirement for every directive.
+It contains the main logic of the directive and it
+returns a list of block-level docutils nodes to be processed by Sphinx.
+It also contains a ``required_arguments`` attribute,
+which tells Sphinx how many arguments are required for the directive.
+
+What are docutils nodes?
+........................
+
+When Sphinx parses a document,
+it creates an "Abstract Syntax Tree" (AST) of nodes
+that represent the content of the document in a structured way,
+that is generally independent of any one
+input (rST, MyST, etc) or output (HTML, LaTeX, etc) format.
+It is a tree because each node can have children nodes, and so on:
+
+.. code-block:: xml
+
+ <document>
+ <paragraph>
+ <text>
+ Hello world!
+
+The docutils_ package provides many `built-in nodes <docutils nodes_>`_,
+to represent different types of content such as
+text, paragraphs, references, tables, etc.
+
+Each node type generally only accepts a specific set of direct child nodes,
+for example the ``document`` node should only contain "block-level" nodes,
+such as ``paragraph``, ``section``, ``table``, etc,
+whilst the ``paragraph`` node should only contain "inline-level" nodes,
+such as ``text``, ``emphasis``, ``strong``, etc.
+
+.. seealso::
+
+ The docutils documentation on
+ `creating directives <docutils directives_>`_, and
+ `creating roles <docutils roles_>`_.
+
+The ``setup`` function
+......................
+
+This function is a requirement.
+We use it to plug our new directive into Sphinx.
+
+.. literalinclude:: examples/helloworld.py
+ :language: python
+ :pyobject: setup
+
+The simplest thing you can do is to call the
+:meth:`.Sphinx.add_role` and :meth:`.Sphinx.add_directive` methods,
+which is what we've done here.
+For this particular call, the first argument is the name of the role/directive itself
+as used in a reStructuredText file.
+In this case, we would use ``hello``. For example:
+
+.. code-block:: rst
+
+ Some intro text here...
+
+ .. hello:: world
+
+ Some text with a :hello:`world` role.
+
+We also return the :ref:`extension metadata <ext-metadata>` that indicates the
+version of our extension, along with the fact that it is safe to use the
+extension for both parallel reading and writing.
+
+Using the extension
+-------------------
+
+The extension has to be declared in your :file:`conf.py` file to make Sphinx
+aware of it. There are two steps necessary here:
+
+#. Add the :file:`_ext` directory to the `Python path`_ using
+ ``sys.path.append``. This should be placed at the top of the file.
+
+#. Update or create the :confval:`extensions` list and add the extension file
+ name to the list
+
+For example:
+
+.. code-block:: python
+
+ import os
+ import sys
+
+ sys.path.append(os.path.abspath("./_ext"))
+
+ extensions = ['helloworld']
+
+.. tip::
+
+ Because we haven't installed our extension as a `Python package`_, we need to
+ modify the `Python path`_ so Sphinx can find our extension. This is why we
+ need the call to ``sys.path.append``.
+
+You can now use the extension in a file. For example:
+
+.. code-block:: rst
+
+ Some intro text here...
+
+ .. hello:: world
+
+ Some text with a :hello:`world` role.
+
+The sample above would generate:
+
+.. code-block:: text
+
+ Some intro text here...
+
+ Hello world!
+
+ Some text with a hello world! role.
+
+
+Further reading
+---------------
+
+This is the very basic principle of an extension
+that creates a new role and directive.
+
+For a more advanced example, refer to :ref:`tutorial-extend-build`.
+
+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/
+.. _docutils roles: https://docutils.sourceforge.io/docs/howto/rst-roles.html
+.. _docutils directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html
+.. _docutils nodes: https://docutils.sourceforge.io/docs/ref/doctree.html
+.. _PyPI: https://pypi.org/
+.. _Python package: https://packaging.python.org/
+.. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
diff --git a/doc/development/tutorials/helloworld.rst b/doc/development/tutorials/helloworld.rst
deleted file mode 100644
index 8940e3d..0000000
--- a/doc/development/tutorials/helloworld.rst
+++ /dev/null
@@ -1,189 +0,0 @@
-Developing a "Hello world" extension
-====================================
-
-The objective of this tutorial is to create a very basic extension that adds a
-new directive. This directive will output a paragraph containing "hello world".
-
-Only basic information is provided in this tutorial. For more information, refer
-to the :doc:`other tutorials <index>` that go into more details.
-
-.. warning::
-
- For this extension, you will need some basic understanding of docutils_
- and Python.
-
-
-Overview
---------
-
-We want the extension to add the following to Sphinx:
-
-* A ``helloworld`` directive, that will simply output the text "hello world".
-
-
-Prerequisites
--------------
-
-We will not be distributing this plugin via `PyPI`_ and will instead include it
-as part of an existing project. This means you will need to use an existing
-project or create a new one using :program:`sphinx-quickstart`.
-
-We assume you are using separate source (:file:`source`) and build
-(:file:`build`) folders. Your extension file could be in any folder of your
-project. In our case, let's do the following:
-
-#. Create an :file:`_ext` folder in :file:`source`
-#. Create a new Python file in the :file:`_ext` folder called
- :file:`helloworld.py`
-
-Here is an example of the folder structure you might obtain:
-
-.. code-block:: text
-
- └── source
-    ├── _ext
- │   └── helloworld.py
-    ├── _static
-    ├── conf.py
-    ├── somefolder
-    ├── index.rst
-    ├── somefile.rst
-    └── someotherfile.rst
-
-
-Writing the extension
----------------------
-
-Open :file:`helloworld.py` and paste the following code in it:
-
-.. literalinclude:: examples/helloworld.py
- :language: python
- :linenos:
-
-Some essential things are happening in this example, and you will see them for
-all directives.
-
-.. rubric:: The directive class
-
-Our new directive is declared in the ``HelloWorld`` class.
-
-.. literalinclude:: examples/helloworld.py
- :language: python
- :linenos:
- :lines: 5-9
-
-This class extends the docutils_' ``Directive`` class. All extensions that
-create directives should extend this class.
-
-.. seealso::
-
- `The docutils documentation on creating directives <docutils directives_>`_
-
-This class contains a ``run`` method. This method is a requirement and it is
-part of every directive. It contains the main logic of the directive and it
-returns a list of docutils nodes to be processed by Sphinx. These nodes are
-docutils' way of representing the content of a document. There are many types of
-nodes available: text, paragraph, reference, table, etc.
-
-.. seealso::
-
- `The docutils documentation on nodes <docutils nodes_>`_
-
-The ``nodes.paragraph`` class creates a new paragraph node. A paragraph
-node typically contains some text that we can set during instantiation using
-the ``text`` parameter.
-
-.. rubric:: The ``setup`` function
-
-.. currentmodule:: sphinx.application
-
-This function is a requirement. We use it to plug our new directive into
-Sphinx.
-
-.. literalinclude:: examples/helloworld.py
- :language: python
- :linenos:
- :lines: 12-
-
-The simplest thing you can do is to call the :meth:`~Sphinx.add_directive` method,
-which is what we've done here. For this particular call, the first argument is
-the name of the directive itself as used in a reST file. In this case, we would
-use ``helloworld``. For example:
-
-.. code-block:: rst
-
- Some intro text here...
-
- .. helloworld::
-
- Some more text here...
-
-We also return the :ref:`extension metadata <ext-metadata>` that indicates the
-version of our extension, along with the fact that it is safe to use the
-extension for both parallel reading and writing.
-
-
-Using the extension
--------------------
-
-The extension has to be declared in your :file:`conf.py` file to make Sphinx
-aware of it. There are two steps necessary here:
-
-#. Add the :file:`_ext` directory to the `Python path`_ using
- ``sys.path.append``. This should be placed at the top of the file.
-
-#. Update or create the :confval:`extensions` list and add the extension file
- name to the list
-
-For example:
-
-.. code-block:: python
-
- import os
- import sys
-
- sys.path.append(os.path.abspath("./_ext"))
-
- extensions = ['helloworld']
-
-.. tip::
-
- We're not distributing this extension as a `Python package`_, we need to
- modify the `Python path`_ so Sphinx can find our extension. This is why we
- need the call to ``sys.path.append``.
-
-You can now use the extension in a file. For example:
-
-.. code-block:: rst
-
- Some intro text here...
-
- .. helloworld::
-
- Some more text here...
-
-The sample above would generate:
-
-.. code-block:: text
-
- Some intro text here...
-
- Hello World!
-
- Some more text here...
-
-
-Further reading
----------------
-
-This is the very basic principle of an extension that creates a new directive.
-
-For a more advanced example, refer to :doc:`todo`.
-
-
-.. _docutils: https://docutils.sourceforge.io/
-.. _docutils directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html
-.. _docutils nodes: https://docutils.sourceforge.io/docs/ref/doctree.html
-.. _PyPI: https://pypi.org/
-.. _Python package: https://packaging.python.org/
-.. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
diff --git a/doc/development/tutorials/index.rst b/doc/development/tutorials/index.rst
index a7eee48..0c5c920 100644
--- a/doc/development/tutorials/index.rst
+++ b/doc/development/tutorials/index.rst
@@ -1,17 +1,12 @@
.. _extension-tutorials-index:
-Extension tutorials
-===================
-
-Refer to the following tutorials to get started with extension development.
-
+Tutorials
+=========
.. toctree::
- :caption: Directive tutorials
- :maxdepth: 1
+ :maxdepth: 2
- helloworld
- todo
- recipe
+ extending_syntax
+ extending_build
+ adding_domain
autodoc_ext
-