=================
Development guide
=================

Adding a new example
====================

All examples must follow a few rules:

1. They must be functions inside a ``test_*.py`` file in the ``tests/``
   directory.
2. They must be self-contained, meaning they take no arguments and have any
   ``imports`` included in the function body. This is so they can be rendered
   as full executable code blocks in the auto-generated Jupyter Notebooks.
3. Any imports should additionally be declared in the docstring. The current
   convention is to include a section like this:

   .. code-block::

      <div class="alert alert-info">

      **Functions used in this example**

      * [name_of_function](../modules/function_module.html#name_of_function)

      </div>

   The ``function_module`` refers to the name of the *documentation page* that
   contains the API documentation for that module.
4. Any new examples should be either added to an existing Notebook output
   configuration or have a new output config. These are declared in
   ``docs/conf.py``.
5. The example should ideally have a test that ensures that it "compiles"--see
   the existing example tests for what this looks like. The most important part
   is to ensure no runtime errors are generated by running the example. Mocks
   should be utilized to ensure no calls to external services actually take
   place (these will probably fail anyways due to lack of authentication.)
