3 files changed, 63 insertions, 0 deletions
diff --git a/doc/development/howtos/builders.rst b/doc/development/howtos/builders.rst
new file mode 100644
index 0000000..7792fbd
--- /dev/null
+++ b/doc/development/howtos/builders.rst
@@ -0,0 +1,28 @@
+Configuring builders
+====================
+
+Discover builders by entry point
+--------------------------------
+
+.. versionadded:: 1.6
+
+:term:`builder` extensions can be discovered by means of `entry points`_ so
+that they do not have to be listed in the :confval:`extensions` configuration
+value.
+
+Builder extensions should define an entry point in the ``"sphinx.builders"``
+group. The name of the entry point needs to match your builder's
+:attr:`~.Builder.name` attribute, which is the name passed to the
+:option:`sphinx-build -b` option. The entry point value should equal the
+dotted name of the extension module. Here is an example of how an entry point
+for 'mybuilder' can be defined in the extension's ``pyproject.toml``
+
+.. code-block:: toml
+
+   [project.entry-points."sphinx.builders"]
+   mybuilder = "my.extension.module"
+
+Note that it is still necessary to register the builder using
+:meth:`~.Sphinx.add_builder` in the extension's :func:`setup` function.
+
+.. _entry points: https://setuptools.pypa.io/en/latest/userguide/entry_point.html
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/howtos/setup_extension.rst b/doc/development/howtos/setup_extension.rst
new file mode 100644
index 0000000..bcb4daf
--- /dev/null
+++ b/doc/development/howtos/setup_extension.rst
@@ -0,0 +1,27 @@
+Depend on another extension
+===========================
+
+Sometimes your extension depends on the functionality of another
+Sphinx extension. Most Sphinx extensions are activated in a
+project's :file:`conf.py` file, but this is not available to you as an
+extension developer.
+
+.. module:: sphinx.application
+   :no-index:
+
+To ensure that another extension is activated as a part of your own extension,
+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 :mod:`sphinx.ext.autodoc` extension:
+
+.. code-block:: python
+
+    def setup(app):
+        app.setup_extension('sphinx.ext.autodoc')
+
+.. note::
+
+   Since your extension will depend on another, make sure to include
+   it as a part of your extension's installation requirements.