8000 Add support for capturing svg, png, and jpeg and _repr_mimebundle_ · sphinx-gallery/sphinx-gallery@370bc6b · GitHub
[go: up one dir, main page]
Skip to content

Commit 370bc6b

Browse files
oscargusoscargus
committed
Add support for capturing svg, png, and jpeg and _repr_mimebundle_
1 parent 1e825be commit 370bc6b

File tree

20 files changed

+299
-28
lines changed

20 files changed

+299
-28
lines changed

‎.circleci/config.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ jobs:
4040
command: |
4141
pip install --progress-bar off --user --upgrade --only-binary ":all:" pip setuptools
4242
pip install --progress-bar off --user --upgrade --only-binary ":all:" numpy matplotlib "pyqt5!=5.15.2,!=5.15.3,!=5.15.8" vtk
43-
pip install --progress-bar off --user --upgrade seaborn statsmodels pillow joblib sphinx pytest traits pyvista memory_profiler "ipython!=8.7.0" plotly graphviz "docutils>=0.18" imageio
43+
pip install --progress-bar off --user --upgrade seaborn statsmodels pillow joblib sphinx pytest traits pyvista memory_profiler "ipython!=8.7.0" plotly graphviz "docutils>=0.18" imageio sphinxcontrib-svg2pdfconverter[CairoSVG]
4444
pip install --progress-bar off "jupyterlite-sphinx>=0.8.0,<0.9.0" "jupyterlite-pyodide-kernel<0.1.0" libarchive-c
4545
pip install --progress-bar off --user --upgrade --pre pydata-sphinx-theme
4646
- save_cache:

‎azure-pipelines.yml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,12 +57,15 @@ stages:
5757
set -eo pipefail
5858
python --version
5959
python -m pip install --user --upgrade pip setuptools wheel
60-
pip install --user --upgrade --progress-bar off "ipython!=8.7.0" numpy seaborn statsmodels matplotlib sphinx pillow pytest pytest-cov joblib "plotly>=4.0" imageio
60+
pip install --user --upgrade --progress-bar off "ipython!=8.7.0" numpy seaborn statsmodels matplotlib sphinx pillow pytest pytest-cov joblib "plotly>=4.0" imageio sphinxcontrib-svg2pdfconverter[CairoSVG]
6161
pip install --user --upgrade --progress-bar off --pre pydata-sphinx-theme
6262
echo "Qt, plotly, VTK"
6363
pip install --user --upgrade --progress-bar off pyvista "pyqt5!=5.15.8" plotly vtk
6464
echo "JupyterLite-related dependencies"
6565
pip install --user --upgrade --progress-bar off "jupyterlite-sphinx>=0.8.0,<0.9.0" "jupyterlite-pyodide-kernel<0.1.0" libarchive-c
66+
echo "Install pre-build cairocffi with DLLs"
67+
pip install --user --upgrade --progress-bar off pipwin
68+
pipwin install cairocffi
6669
displayName: Setup pip environment
6770
- script: pip list
6871
displayName: pip list

‎continuous_integration/azure/install.sh

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ if [ "$DISTRIB" == "conda" ]; then
1515
echo "##vso[task.prependpath]$CONDA/bin"
1616
export PATH=${CONDA}/bin:${PATH}
1717
CONDA_TO_INSTALL="python=$PYTHON_VERSION pip numpy setuptools matplotlib pillow pytest pytest-cov coverage seaborn statsmodels 'plotly>=4.0' joblib flake8 wheel libiconv graphviz memory_profiler \"ipython!=8.7.0\" pypandoc"
18-
PIP_DEPENDENCIES="check-manifest jupyterlite-sphinx>=0.8.0,<0.9.0 jupyterlite-pyodide-kernel<0.1.0 libarchive-c"
18+
PIP_DEPENDENCIES="check-manifest jupyterlite-sphinx>=0.8.0,<0.9.0 jupyterlite-pyodide-kernel<0.1.0 libarchive-c sphinxcontrib-svg2pdfconverter[CairoSVG]"
1919
if [ "$SPHINX_VERSION" == "" ]; then
2020
PIP_DEPENDENCIES="${PIP_DEPENDENCIES} sphinx jinja2<=3.0.3"
2121
elif [ "$SPHINX_VERSION" == "dev" ]; then

‎dev-requirements.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,4 @@ absl-py
1616
graphviz
1717
packaging
1818
jupyterlite-sphinx
19+
sphinxcontrib-svg2pdfconverter[CairoSVG]

‎doc/advanced.rst

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -143,12 +143,16 @@ Write a custom image scraper
143143
By default, Sphinx-Gallery supports image scraping for Matplotlib
144144
(:func:`~sphinx_gallery.scrapers.matplotlib_scraper`). If you wish to capture
145145
output from other python packages, first determine if the object you wish to
146-
capture has a ``_repr_html_`` method. If so, you can use the configuration
147-
``capture_repr`` (:ref:`capture_repr`) to control the display of the object,
148-
without the need to write a custom scraper. This configuration allows capture
149-
of the raw html output, in a process similar to other html-based displays such
150-
as `jupyter <https://jupyter.org/>`_. If the first option does not work,
151-
this section describes how to write a custom scraper.
146+
capture has any of the other supported capture methods: ``_repr_html_``,
147+
``_repr_png_``, ``_repr_jpeg_``, and ``_repr_svg_``. If so, you can use the
148+
configuration ``capture_repr`` (:ref:`capture_repr`) to control the display of
149+
the object, without the need to write a custom scraper. This configuration allows
150+
capture of the raw html/png/jpeg/svg output, in a process similar to other enriched
151+
displays such as `jupyter <https://jupyter.org/>`_. If the object supports
152+
``_repr_mimebundle_``, adding, e.g., ``_repr_svg_`` to ``capture_repr`` will also
153+
look for SVG in the returned MIME-bundle.
154+
155+
If the first option does not work, this section describes how to write a custom scraper.
152156

153157
Image scrapers are functions (or callable class instances) that do the following
154158
things:

‎doc/conf.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -327,6 +327,7 @@ def setup(app):
327327
'sklearn': ('https://scikit-learn.org/stable', None),
328328
'sphinx': ('https://www.sphinx-doc.org/en/master', None),
329329
'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
330+
'ipython': ('https://ipython.readthedocs.io/en/stable/', None),
330331
}
331332

332333
examples_dirs = ['../examples', '../tutorials']

‎doc/configuration.rst

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1856,8 +1856,21 @@ are:
18561856
* ``__str__`` - returns a string containing a nicely printable representation
18571857
of an object. This is what is used when you ``print()`` an object or pass it
18581858
to ``format()``.
1859-
* ``_repr_html_`` - returns a HTML version of the object. This method is only
1860-
present in some objects, for example, pandas dataframes.
1859+
* ``_repr_html_`` - returns an HTML version of the object.
1860+
* ``_repr_png_`` - returns a PNG version of the object.
1861+
* ``_repr_jpeg_`` - returns a JPEG version of the object.
1862+
* ``_repr_svg_`` - returns an SVG version of the object.
1863+
1864+
Note that the last four methods are only available for some objects. For example,
1865+
Pandas dataframes, SymPy expressions, and GraphViz graphs, support one or more of
1866+
these formats.
1867+
1868+
.. note::
1869+
1870+
Some objects support :py:meth:`~MyObject._repr_mimebundle_`, which is the preferred
1871+
way to access enriched representations. By specifying, e.g., ``_repr_svg_``,
1872+
Sphinx-Gallery will first look for an SVG in the MIME bundle.
1873+
If not, it will call ``_repr_svg_`` if available.
18611874

18621875
Output capture can be controlled globally by the ``capture_repr`` configuration
18631876
setting or file-by-file by adding a comment to the example file, which overrides

‎examples/no_output/just_code.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
55
This demonstrates an example ``.py`` file that is not executed when gallery is
66
generated (see :ref:`build_pattern`) but nevertheless gets included as an
7-
example. Note that no output is capture as this file is not executed.
7+
example. Note that no output is captured as this file is not executed.
88
"""
99

1010
# Code source: Óscar Nájera

‎examples/plot_3_capture_repr.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@
111111
# default ``capture_repr`` setting, ``_repr_html_`` is attempted to be captured
112112
# first. If this method does not exist, the ``__repr__`` method would be
113113
# captured. If the ``__repr__`` also does not exist (unlikely for non-user
114-
# defined objects), nothing would be captured. For example, if the the
114+
# defined objects), nothing would be captured. For example, if the
115115
# configuration was set to ``'capture_repr': ('_repr_html_')`` nothing would be
116116
# captured for example 2 as ``b`` does not have a ``_repr_html_``.
117117
# You can change the 'representations' in the ``capture_repr`` tuple to finely

‎sphinx_gallery/directives.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ class ImageSg(images.Image):
128128
/plot_types/basic/images/sphx_glr_bar_001_2_00x.png 2.00x
129129
:class: sphx-glr-single-img
130130
131-
The resulting html is::
131+
The resulting HTML is::
132132
133133
<img src="sphx_glr_bar_001_hidpi.png"
134134
srcset="_images/sphx_glr_bar_001.png,

0 commit comments

Comments
 (0)
0