This is the pyfar gallery. It contains examples of applications pyfar and its sub-packages can be used for. Each of the notebooks in the gallery has a binder link to start an interactive jupyter session. The rendered version of the gallery is hosted on readthedocs.org.
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- 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-featureNow 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.
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.
A very bare template for new notebooks is provided in docs/_templates/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
└── resourcesNote 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
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.ipynbFinally, 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.ipynbUnless otherwise stated source code, graphics, and audio files © 2024 by the pyfar developers are licensed under CC BY 4.0.