contributing.md

================= 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::

   Functions used in this example

   • name_of_function

   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.)