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:

.. code-block:: python

   from docutils import nodes
   from docutils.parsers.rst import Directive


   class HelloWorld(Directive):

       def run(self):
           paragraph_node = nodes.paragraph(text='Hello World!')
           return [paragraph_node]


   def setup(app):
       app.add_directive("helloworld", HelloWorld)


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.

.. code-block:: python

   class HelloWorld(Directive):

       def run(self):
           paragraph_node = nodes.paragraph(text='Hello World!')
           return [paragraph_node]

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.

.. code-block:: python

   def setup(app):
       app.add_directive("helloworld", HelloWorld)

The simplest thing you can do it 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 an rST file. In this
case, we would use ``helloworld``. For example:

.. code-block:: rst

   Some intro text here...

   .. helloworld::

   Some more text here...


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: http://docutils.sourceforge.net/
.. _docutils directives: http://docutils.sourceforge.net/docs/howto/rst-directives.html
.. _docutils nodes: http://docutils.sourceforge.net/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