.. image:: https://readthedocs.org/projects/pyfar-gallery/badge/?version=latest :target: https://pyfar-gallery.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status .. image:: https://circleci.com/gh/pyfar/gallery.svg?style=shield :target: https://circleci.com/gh/pyfar/gallery .. image:: https://mybinder.org/badge_logo.svg :target: https://mybinder.org/v2/gh/pyfar/gallery/main?filepath=docs/gallery .. image:: https://mirrors.creativecommons.org/presskit/buttons/80x15/svg/by.svg :target: https://mirrors.creativecommons.org/presskit/icons/by.svg?ref=chooser-v1 :height: 20
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
.
.. _binder: https://mybinder.org/v2/gh/pyfar/gallery/main?filepath=docs/gallery .. _readthedocs.org: https://pyfar-gallery.readthedocs.io/en/latest
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 <https://desktop.github.com/>
, extensions in Visual Studio Code <https://code.visualstudio.com/>
...
Fork <https://docs.github.com/en/get-started/quickstart/fork-a-repo/>
_ the gallery
repo on GitHub... code-block:: shell
git clone https://github.com/YOUR_USERNAME/gallery.git
cd gallery
.. code-block:: shell
conda create --name gallery python
conda activate gallery
pip install -r requirements.txt
docs/gallery/interactive
aren't cleaned from outputs. After that, the automatic changes can be added and committed::.. code-block:: shell
pre-commit install
feature/branch-name
or bugfix/branch-name
)::.. code-block:: shell
git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
.. code-block:: shell
git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature
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 <https://github.com/pyfar/gallery/blob/main/docs/_templates/template.ipynb>
_. It is highly recommended to use it for consistency with other notebooks.
.. code-block:: shell
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
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
.. code-block:: json
"nbsphinx": {
"execute": "never"
},
as part of their JSON meta-data.
For more information see the nbsphinx documentation <https://nbsphinx.readthedocs.io/en/latest/never-execute.html>
_
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
.. code-block:: json
"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.
.. code-block:: python
sphinx_thumbnails = {
'gallery/interactive/your_new_notebook': '_static/thumbnail_added.png',
}
The respective file tree for this example would look like this:
.. code-block:: shell
docs
├── Makefile
├── _build
├── _static
│ └── thumbnail_added.png
├── conf.py
├── gallery
│ ├── interactive
│ │ └── your_new_notebook.ipynb
Finally, add the notebook to an appropriate nbgallery
inside the docs/index.rst
. For example:
.. code-block:: rst
.. nbgallery::
:caption: Getting Started
:name: pyfar_gallery
:glob:
:reversed:
gallery/interactive/your_new_notebook.ipynb
Unless otherwise stated source code, graphics, and audio files © 2024 by the pyfar developers <https://github.com/orgs/pyfar/people>
are licensed under CC BY 4.0 <http://creativecommons.org/licenses/by/4.0/?ref=chooser-v1>
.
.. image:: https://mirrors.creativecommons.org/presskit/buttons/88x31/svg/by.svg :target: https://mirrors.creativecommons.org/presskit/icons/by.svg?ref=chooser-v1