Contribute to the Gallery#

Get Started#

Ready to contribute? Here’s how to set up pyfar_gallery for local development using the command-line interface. Note that several alternative user interfaces exist, e.g., the Git GUI, GitHub Desktop, extensions in Visual Studio Code …

Fork the gallery repo on GitHub.
Clone your fork locally and cd into the gallery directory:

git clone https://github.com/YOUR_USERNAME/gallery.git
cd gallery

Install your local copy into a virtualenv. Assuming you have Anaconda or Miniconda installed, this is how you set up your fork for local development:

conda create --name gallery python
conda activate gallery
pip install -r requirements.txt

You will also require pandoc. If you don’t have it installed, you can download it from the official website. Alternatively, you can install it using conda using the conda-forge channel:

conda install -c conda-forge pandoc

Set up pre-commit hooks. This will cause commits to fail and clean all notebooks if the notebooks in docs/gallery/interactive aren’t cleaned from outputs. After that, the automatic changes can be added and committed:

pre-commit install

Create a branch for local development. Indicate the intention of your branch in its respective name (i.e. feature/branch-name or bugfix/branch-name):

 git checkout -b name-of-your-bugfix-or-feature

Now you can make your changes locally.

Commit your changes and push your branch to GitHub:

git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature

Submit a pull request on the develop branch through the GitHub website.

Structure#

The gallery is separated into interactive and static notebooks, allowing to include notebooks for which execution on readthedocs or CircleCI is not feasible. This could be due to the need for specific hardware, such as audio interfaces or other io-devices, as well as notebooks with very long execution times or computational demands.

To add notebooks to the gallery, simply place them inside docs/gallery/interactive or docs/gallery/static, respectively. Note that all notebooks added to the folder interactive should not contain output for any of the cells, see the section above for setting up the pre-commit hooks to automatically clean the notebooks from outputs,

A very bare template for new notebooks is provided in docs/contribute/template.ipympl. It is highly recommended to use it for consistency with other notebooks.

docs
├── Makefile
├── _build
├── _templates
│   └── template.ipynb
├── _static
├── conf.py
├── gallery
│   ├── interactive
│   │   ├── your_new_notebook.ipynb
│   │   └── interactive_demo.ipynb
│   └── static
│       └── pre_executed_notebook.ipynb
├── index.rst
├── make.bat
└── resources

Metadata for static notebooks#

Note that notebooks placed in the static folder omitted from unit testing on CircleCI and hence need appropriate offline testing. Static notebooks further need to include the setting

"nbsphinx": {
    "execute": "never"
},

as part of their JSON meta-data.

For more information see the nbsphinx documentation

Thumbnails#

Nbspinx does select the last output of a notebook as thumbnail by default. If a specific output from a notebook should be selected as thumbnail, the meta data of the cell containing the output must be tagged

"metadata": {
    "nbsphinx-thumbnail": {}
}

If the notebook contains no output, a thumbnail can be added by placing a file in the docs/gallery/_static folder. The filename and notebook name need to be added to the nbspinx_thumbnails dictionary in the conf.py file.

sphinx_thumbnails = {
    'gallery/interactive/your_new_notebook': '_static/thumbnail_added.png',
}

The respective file tree for this example would look like this:

docs
├── Makefile
├── _build
├── _static
│   └── thumbnail_added.png
├── conf.py
├── gallery
│   ├── interactive
│   │   └── your_new_notebook.ipynb

Adding a notebook to the gallery#

Finally, add the notebook to an appropriate nbgallery inside the docs/index.rst. For example:

.. nbgallery::
   :caption: Getting Started
   :name: pyfar_gallery
   :glob:
   :reversed:

   gallery/interactive/your_new_notebook.ipynb

Licensing#

Unless otherwise stated the notebooks are released under © 2024 by the pyfar developers are licensed under CC BY 4.0. If required, a different but compatible license can be chosen for single notebooks. Simply adapt the author name and license information in the respective section at the end of the notebook. Note that if a notebook contains code or content from other sources, this should be clearly stated in the notebook.