| Name | sphinx-gallery JSON |
| Version |
0.18.0
JSON |
| download |
| home_page | None |
| Summary | A Sphinx extension that builds an HTML gallery of examples from any set of Python scripts. |
| upload_time | 2024-10-09 06:01:28 |
| maintainer | None |
| docs_url | https://pythonhosted.org/sphinx-gallery/ |
| author | None |
| requires_python | >=3.8 |
| license | 3-clause BSD |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
==============
Sphinx-Gallery
==============
.. image:: https://img.shields.io/pypi/v/sphinx-gallery
:target: https://pypi.org/project/sphinx-gallery/
:alt: PyPI
.. image:: https://img.shields.io/conda/vn/conda-forge/sphinx-gallery
:target: https://anaconda.org/conda-forge/sphinx-gallery
:alt: Conda-forge
.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3741780.svg
:target: https://doi.org/10.5281/zenodo.3741780
:alt: Zenodo DOI
.. image:: https://dev.azure.com/sphinx-gallery/sphinx-gallery/_apis/build/status/sphinx-gallery.sphinx-gallery?branchName=master
:target: https://dev.azure.com/sphinx-gallery/sphinx-gallery/_build/latest?definitionId=1&branchName=master
:alt: Azure CI status
.. image:: https://circleci.com/gh/sphinx-gallery/sphinx-gallery.svg?style=shield
:target: https://circleci.com/gh/sphinx-gallery/sphinx-gallery
:alt: CircleCI status
.. image:: https://codecov.io/github/sphinx-gallery/sphinx-gallery/badge.svg?branch=master&service=github(
:target: https://app.codecov.io/github/sphinx-gallery/sphinx-gallery
:alt: Code coverage
.. tagline-begin-content
A `Sphinx <https://www.sphinx-doc.org/en/master/>`_ extension that builds an
HTML gallery of examples from any set of Python scripts.
Check out the `documentation`_ for introductions on how to use it and more...
.. tagline-end-content
.. image:: doc/_static/demo.png
:width: 80%
:alt: A demo of a gallery generated by Sphinx-Gallery
Quickstart
==========
Sphinx-Gallery can be used to generate an example gallery from ``.py`` files,
for a library,
as well as a stand-alone web page showcasing examples of a particular
Python package, module, or class.
Let's get started with a simple example or check out the
`documentation`_ for introductions on how
to use it and more...
Install via ``pip``
-------------------
.. installation-begin-content
You can do a direct install via ``pip`` by using:
.. code-block:: bash
$ pip install sphinx-gallery
.. tip::
Sphinx-Gallery also has support for scraping images from Matplotlib
and Matplotlib-based packages such as Seaborn.
We recommend installing system ``optipng`` binaries to reduce
the file sizes of the generated PNG files.
.. installation-end-content
Add examples to your docs
-------------------------
Let's assume simple scenario, you have a Python package with a directory structure like this:
.. code-block::
├── doc
│ ├── conf.py
│ ├── index.rst
| ├── make.bat
│ └── Makefile
├── my_python_module
│ ├── __init__.py
│ └── mod.py
└── examples
├── plot_example.py
└── README.txt (or .rst)
Enable Sphinx-Gallery by adding the following to your ``doc/conf.py``:
.. code-block:: python
extensions = [
...
'sphinx_gallery.gen_gallery',
]
# path to the examples scripts
sphinx_gallery_conf = {
'examples_dirs': '../examples', # path to your example scripts
'gallery_dirs': 'auto_examples', # path to where to save gallery generated output
}
Finally just compile your docs as usual.
Sphinx-Gallery will generate reST files, adding execution outputs, and save them in ``auto_examples/``.
Add a link to ``auto_examples/index.rst`` to include the gallery in your documentation.
Who uses Sphinx-Gallery
=======================
An incomplete list:
.. projects_list_start
* `Apache TVM <https://tvm.apache.org/docs/tutorial/index.html>`_
* `Astropy <https://docs.astropy.org/en/stable/generated/examples/index.html>`_
* `auto-sklearn <https://automl.github.io/auto-sklearn/master/examples/index.html>`_
* `Biotite <https://www.biotite-python.org/examples/gallery/index.html>`_
* `Cartopy <https://scitools.org.uk/cartopy/docs/latest/gallery/>`_
* `FURY <https://fury.gl/latest/auto_examples/index.html>`_
* `pyGIMLi <https://www.pygimli.org/_examples_auto/index.html>`_
* `HyperSpy <https://hyperspy.org/hyperspy-doc/current/>`_
* `kikuchipy <https://kikuchipy.org>`_
* `Matplotlib <https://matplotlib.org/stable/index.html>`_
* `MNE-Python <https://mne.tools/stable/auto_examples/index.html>`_
* `napari <https://napari.org/stable/gallery.html>`_
* `Nestle <http://kylebarbary.com/nestle/examples/index.html>`_
* `NetworkX <https://networkx.org/documentation/stable/auto_examples/index.html>`_
* `Neuraxle <https://www.neuraxle.org/stable/examples/index.html>`_
* `Nilearn <https://nilearn.github.io/stable/auto_examples/index.html>`_
* `OpenML <https://openml.github.io/openml-python/main/examples/index.html>`_
* `OpenTURNS <https://openturns.github.io/openturns/latest/examples/examples.html>`_
* `Optuna <https://optuna.readthedocs.io/en/stable/tutorial/index.html>`_
* `PlasmaPy <https://docs.plasmapy.org/en/latest/examples.html>`_
* `PyGMT <https://www.pygmt.org/latest/gallery/index.html>`_
* `pyRiemann <https://pyriemann.readthedocs.io/en/latest/index.html>`_
* `PyStruct <https://pystruct.github.io/auto_examples/index.html>`_
* `PySurfer <https://pysurfer.github.io/>`_
* `PyTorch tutorials <https://pytorch.org/tutorials>`_
* `PyVista <https://docs.pyvista.org/examples/>`_
* `pyxem <https://pyxem.readthedocs.io>`_
* `RADIS <https://radis.readthedocs.io/en/latest/auto_examples/index.html>`_
* `scikit-image <https://scikit-image.org/docs/dev/auto_examples/>`_
* `scikit-learn <https://scikit-learn.org/stable/auto_examples/index.html>`_
* `SimPEG <https://docs.simpeg.xyz/content/examples/>`_
* `Sphinx-Gallery <https://sphinx-gallery.github.io/stable/auto_examples/index.html>`_
* `SunPy <https://docs.sunpy.org/en/stable/generated/gallery/index.html>`_
* `Tonic <https://tonic.readthedocs.io/en/latest/auto_examples/index.html>`_
* `TorchIO <https://torchio.readthedocs.io/auto_examples/index.html>`_
.. projects_list_end
Contributing
============
You can get the latest development source from our `Github repository
<https://github.com/sphinx-gallery/sphinx-gallery>`_. You need
``setuptools`` installed in your system to install Sphinx-Gallery. For example,
you can do:
.. code-block:: console
$ git clone https://github.com/sphinx-gallery/sphinx-gallery
$ cd sphinx-gallery
$ conda install graphviz # if using conda, you can get graphviz this way
$ pip install -e .[dev]
Check that you are all set by running:
.. code-block:: console
$ pytest sphinx_gallery
How to cite
===========
.. citation-begin-content
If you would like to cite Sphinx-Gallery you can do so using our `Zenodo
deposit <https://zenodo.org/record/3741780>`_.
.. _documentation: https://sphinx-gallery.github.io/
.. citation-end-content
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-gallery",
"maintainer": null,
"docs_url": "https://pythonhosted.org/sphinx-gallery/",
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "\u00d3scar N\u00e1jera <najera.oscar@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ac/84/e4b4cde6ea2f3a1dd7d523dcf28260e93999b4882cc352f8bc6a14cbd848/sphinx_gallery-0.18.0.tar.gz",
"platform": null,
"description": "==============\nSphinx-Gallery\n==============\n\n.. image:: https://img.shields.io/pypi/v/sphinx-gallery\n :target: https://pypi.org/project/sphinx-gallery/\n :alt: PyPI\n\n.. image:: https://img.shields.io/conda/vn/conda-forge/sphinx-gallery\n :target: https://anaconda.org/conda-forge/sphinx-gallery\n :alt: Conda-forge\n\n.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3741780.svg\n :target: https://doi.org/10.5281/zenodo.3741780\n :alt: Zenodo DOI\n\n.. image:: https://dev.azure.com/sphinx-gallery/sphinx-gallery/_apis/build/status/sphinx-gallery.sphinx-gallery?branchName=master\n :target: https://dev.azure.com/sphinx-gallery/sphinx-gallery/_build/latest?definitionId=1&branchName=master\n :alt: Azure CI status\n\n.. image:: https://circleci.com/gh/sphinx-gallery/sphinx-gallery.svg?style=shield\n :target: https://circleci.com/gh/sphinx-gallery/sphinx-gallery\n :alt: CircleCI status\n\n.. image:: https://codecov.io/github/sphinx-gallery/sphinx-gallery/badge.svg?branch=master&service=github(\n :target: https://app.codecov.io/github/sphinx-gallery/sphinx-gallery\n :alt: Code coverage\n\n\n.. tagline-begin-content\n\nA `Sphinx <https://www.sphinx-doc.org/en/master/>`_ extension that builds an\nHTML gallery of examples from any set of Python scripts.\nCheck out the `documentation`_ for introductions on how to use it and more...\n\n.. tagline-end-content\n\n.. image:: doc/_static/demo.png\n :width: 80%\n :alt: A demo of a gallery generated by Sphinx-Gallery\n\nQuickstart\n==========\n\nSphinx-Gallery can be used to generate an example gallery from ``.py`` files,\nfor a library,\nas well as a stand-alone web page showcasing examples of a particular\nPython package, module, or class.\n\nLet's get started with a simple example or check out the\n `documentation`_ for introductions on how\n to use it and more...\n\nInstall via ``pip``\n-------------------\n\n.. installation-begin-content\n\nYou can do a direct install via ``pip`` by using:\n\n.. code-block:: bash\n\n $ pip install sphinx-gallery\n\n.. tip::\n Sphinx-Gallery also has support for scraping images from Matplotlib\n and Matplotlib-based packages such as Seaborn.\n We recommend installing system ``optipng`` binaries to reduce\n the file sizes of the generated PNG files.\n\n.. installation-end-content\n\nAdd examples to your docs\n-------------------------\n\nLet's assume simple scenario, you have a Python package with a directory structure like this:\n\n.. code-block::\n\n \u251c\u2500\u2500 doc\n \u2502 \u251c\u2500\u2500 conf.py\n \u2502 \u251c\u2500\u2500 index.rst\n | \u251c\u2500\u2500 make.bat\n \u2502 \u2514\u2500\u2500 Makefile\n \u251c\u2500\u2500 my_python_module\n \u2502 \u251c\u2500\u2500 __init__.py\n \u2502 \u2514\u2500\u2500 mod.py\n \u2514\u2500\u2500 examples\n \u251c\u2500\u2500 plot_example.py\n \u2514\u2500\u2500 README.txt (or .rst)\n\nEnable Sphinx-Gallery by adding the following to your ``doc/conf.py``:\n\n.. code-block:: python\n\n extensions = [\n ...\n 'sphinx_gallery.gen_gallery',\n ]\n\n # path to the examples scripts\n sphinx_gallery_conf = {\n 'examples_dirs': '../examples', # path to your example scripts\n 'gallery_dirs': 'auto_examples', # path to where to save gallery generated output\n }\n\nFinally just compile your docs as usual.\nSphinx-Gallery will generate reST files, adding execution outputs, and save them in ``auto_examples/``.\nAdd a link to ``auto_examples/index.rst`` to include the gallery in your documentation.\n\nWho uses Sphinx-Gallery\n=======================\n\nAn incomplete list:\n\n.. projects_list_start\n\n* `Apache TVM <https://tvm.apache.org/docs/tutorial/index.html>`_\n* `Astropy <https://docs.astropy.org/en/stable/generated/examples/index.html>`_\n* `auto-sklearn <https://automl.github.io/auto-sklearn/master/examples/index.html>`_\n* `Biotite <https://www.biotite-python.org/examples/gallery/index.html>`_\n* `Cartopy <https://scitools.org.uk/cartopy/docs/latest/gallery/>`_\n* `FURY <https://fury.gl/latest/auto_examples/index.html>`_\n* `pyGIMLi <https://www.pygimli.org/_examples_auto/index.html>`_\n* `HyperSpy <https://hyperspy.org/hyperspy-doc/current/>`_\n* `kikuchipy <https://kikuchipy.org>`_\n* `Matplotlib <https://matplotlib.org/stable/index.html>`_\n* `MNE-Python <https://mne.tools/stable/auto_examples/index.html>`_\n* `napari <https://napari.org/stable/gallery.html>`_\n* `Nestle <http://kylebarbary.com/nestle/examples/index.html>`_\n* `NetworkX <https://networkx.org/documentation/stable/auto_examples/index.html>`_\n* `Neuraxle <https://www.neuraxle.org/stable/examples/index.html>`_\n* `Nilearn <https://nilearn.github.io/stable/auto_examples/index.html>`_\n* `OpenML <https://openml.github.io/openml-python/main/examples/index.html>`_\n* `OpenTURNS <https://openturns.github.io/openturns/latest/examples/examples.html>`_\n* `Optuna <https://optuna.readthedocs.io/en/stable/tutorial/index.html>`_\n* `PlasmaPy <https://docs.plasmapy.org/en/latest/examples.html>`_\n* `PyGMT <https://www.pygmt.org/latest/gallery/index.html>`_\n* `pyRiemann <https://pyriemann.readthedocs.io/en/latest/index.html>`_\n* `PyStruct <https://pystruct.github.io/auto_examples/index.html>`_\n* `PySurfer <https://pysurfer.github.io/>`_\n* `PyTorch tutorials <https://pytorch.org/tutorials>`_\n* `PyVista <https://docs.pyvista.org/examples/>`_\n* `pyxem <https://pyxem.readthedocs.io>`_\n* `RADIS <https://radis.readthedocs.io/en/latest/auto_examples/index.html>`_\n* `scikit-image <https://scikit-image.org/docs/dev/auto_examples/>`_\n* `scikit-learn <https://scikit-learn.org/stable/auto_examples/index.html>`_\n* `SimPEG <https://docs.simpeg.xyz/content/examples/>`_\n* `Sphinx-Gallery <https://sphinx-gallery.github.io/stable/auto_examples/index.html>`_\n* `SunPy <https://docs.sunpy.org/en/stable/generated/gallery/index.html>`_\n* `Tonic <https://tonic.readthedocs.io/en/latest/auto_examples/index.html>`_\n* `TorchIO <https://torchio.readthedocs.io/auto_examples/index.html>`_\n\n.. projects_list_end\n\nContributing\n============\n\nYou can get the latest development source from our `Github repository\n<https://github.com/sphinx-gallery/sphinx-gallery>`_. You need\n``setuptools`` installed in your system to install Sphinx-Gallery. For example,\nyou can do:\n\n.. code-block:: console\n\n $ git clone https://github.com/sphinx-gallery/sphinx-gallery\n $ cd sphinx-gallery\n $ conda install graphviz # if using conda, you can get graphviz this way\n $ pip install -e .[dev]\n\n\nCheck that you are all set by running:\n\n.. code-block:: console\n\n $ pytest sphinx_gallery\n\nHow to cite\n===========\n\n.. citation-begin-content\n\nIf you would like to cite Sphinx-Gallery you can do so using our `Zenodo\ndeposit <https://zenodo.org/record/3741780>`_.\n\n.. _documentation: https://sphinx-gallery.github.io/\n\n.. citation-end-content\n",
"bugtrack_url": null,
"license": "3-clause BSD",
"summary": "A Sphinx extension that builds an HTML gallery of examples from any set of Python scripts.",
"version": "0.18.0",
"project_urls": {
"Documentation": "https://sphinx-gallery.github.io",
"Source": "https://github.com/sphinx-gallery/sphinx-gallery"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a3f38fd1ef84f318d404dcd713c54647e616d93396beb28db216e281ba86d728",
"md5": "9ea427fe9b76a5a578b2b280497cac42",
"sha256": "54317366e77b182672797e5b46ab13cca9a27eafc3142c59dc4c211d4afe3420"
},
"downloads": -1,
"filename": "sphinx_gallery-0.18.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9ea427fe9b76a5a578b2b280497cac42",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 448725,
"upload_time": "2024-10-09T06:01:25",
"upload_time_iso_8601": "2024-10-09T06:01:25.930785Z",
"url": "https://files.pythonhosted.org/packages/a3/f3/8fd1ef84f318d404dcd713c54647e616d93396beb28db216e281ba86d728/sphinx_gallery-0.18.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ac84e4b4cde6ea2f3a1dd7d523dcf28260e93999b4882cc352f8bc6a14cbd848",
"md5": "e8f7296b958fd8e015996a99893aa691",
"sha256": "4b5b5bc305348c01d00cf66ad852cfd2dd8b67f7f32ae3e2820c01557b3f92f9"
},
"downloads": -1,
"filename": "sphinx_gallery-0.18.0.tar.gz",
"has_sig": false,
"md5_digest": "e8f7296b958fd8e015996a99893aa691",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 466371,
"upload_time": "2024-10-09T06:01:28",
"upload_time_iso_8601": "2024-10-09T06:01:28.005137Z",
"url": "https://files.pythonhosted.org/packages/ac/84/e4b4cde6ea2f3a1dd7d523dcf28260e93999b4882cc352f8bc6a14cbd848/sphinx_gallery-0.18.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-09 06:01:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sphinx-gallery",
"github_project": "sphinx-gallery",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"circle": true,
"lcname": "sphinx-gallery"
}
