10000 Release0.10.1 by lucyleeow · Pull Request #881 · sphinx-gallery/sphinx-gallery · GitHub
[go: up one dir, main page]

Skip to content

Release0.10.1 #881

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 13, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
8000
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions CHANGES.rst
Original file line number Diff line number Diff line change
@@ -1,6 +1,37 @@
Change Log
==========

v0.10.1
-------

Support for Python 3.6 dropped in this release. Requirement is Python >=3.7.

**Implemented enhancements:**

- Feature Request: ``reset_modules`` to be applied after each or all examples `#866 <https://github.com/sphinx-gallery/sphinx-gallery/issues/866>`__
- Enable ``reset_modules`` to run either before or after examples, or both `#870 <https://github.com/sphinx-gallery/sphinx-gallery/pull/870>`__ (`MatthewFlamm <https://github.com/MatthewFlamm>`__)

**Fixed bugs:**

- embed_code_links throwing <exception: list indices must be integers or slices, not str> `#879 <https://github.com/sphinx-gallery/sphinx-gallery/issues/879>`__
- ``0.10.0`` breaks ``sphinx_gallery.load_style`` `#878 <https://github.com/sphinx-gallery/sphinx-gallery/issues/878>`__
- Add imagesg directive in load style `#880 <https://github.com/sphinx-gallery/sphinx-gallery/pull/880>`__ (`lucyleeow <https://github.com/lucyleeow>`__)
- Use bools for ‘plot_gallery’ in sphinx_gallery_conf `#863 <https://github.com/sphinx-gallery/sphinx-gallery/pull/863>`__ (`timhoffm <https://github.com/timhoffm>`__)

**Closed issues:**

- Idea: make galleries out of the “testing” folder to use each unit test as an example. `#875 <https://github.com/sphinx-gallery/sphinx-gallery/issues/875>`__
- Output text in dark mode is not visible `#869 <https://github.com/sphinx-gallery/sphinx-gallery/issues/869>`__
- Using a .gif image works in ``.rst`` sphinx build but not inside example gener 8000 ated with sphinx-gallery `#868 <https://github.com/sphinx-gallery/sphinx-gallery/issues/868>`__
- How to avoid capture of tqdm progress bars `#867 <https://github.com/sphinx-gallery/sphinx-gallery/issues/867>`__

**Merged pull requests:**

- DOC Add reference to sphinx-codeautolink `#874 <https://github.com/sphinx-gallery/sphinx-gallery/pull/874>`__ (`felix-hilden <https://github.com/felix-hilden>`__)
- Add Neuraxle to “Who uses Sphinx-Gallery” `#873 <https://github.com/sphinx-gallery/sphinx-gallery/pull/873>`__ (`guillaume-chevalier <https://github.com/guillaume-chevalier>`__)
- DOC Fix typo in dummy images doc `#871 <https://github.com/sphinx-gallery/sphinx-gallery/pull/871>`__ (`lucyleeow <https://github.com/lucyleeow>`__)
- CI: Fix CircleCI `#865 <https://github.com/sphinx-gallery/sphinx-gallery/pull/865>`__ (`larsoner <https://github.com/larsoner>`__)

v0.10.0
-------

Expand Down
22 changes: 12 additions & 10 deletions doc/advanced.rst
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@ that are useful for Sphinx-Gallery.
Cleaning the gallery files
--------------------------

Once your gallery is working you might need completely remove all generated files by
Sphinx-Gallery to have a clean build. For this we recommend adding the following
to your Sphinx ``Makefile``:
Once your gallery is working you might need completely remove all generated
files by Sphinx-Gallery to have a clean build. For this we recommend adding the
following to your Sphinx ``Makefile``:

.. code-block:: bash

Expand Down Expand Up @@ -393,9 +393,9 @@ function (see :ref:`reset_modules`).
examples themselves is discouraged due to the inconsistency
that results between the rendered examples and local outputs.

If the custom function needs to be aware of whether it is being run before or after
an example, a function signature with three parameters can be used, where the third parameter
is required to be named ``when``::
If the custom function needs to be aware of whether it is being run before or
after an example, a function signature with three parameters can be used, where
the third parameter is required to be named ``when``::

def reset_mpl(gallery_conf, fname, when):

Expand All @@ -404,10 +404,12 @@ is required to be named ``when``::
if when == 'after' and fname=='dashed_lines':
mpl.rcParams['lines.linestyle'] = '-'

The value passed into ``when`` can be ``before`` or ``after``.
If ``reset_modules_order`` in the :ref:`configuration <reset_modules_order>` is set to ``before`` or
``after``, ``when`` will always be the same value. This function signature
is only useful when used in conjuction with ``reset_modules_order`` set to ``both``.
The value passed into ``when`` can be ``'before'`` or ``'after'``.
If ``reset_modules_order`` in the :ref:`configuration <reset_modules_order>`
is set to ``'before'`` or ``'after'``, ``when`` will always be the same value
as what ``reset_modules_order`` is set to.
This function signature is only useful when used in conjuction with
``reset_modules_order`` set to ``'both'``.

Altering Sphinx-Gallery CSS
===========================
Expand Down
87 changes: 52 additions & 35 deletions doc/configuration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -151,16 +151,18 @@ instead of ``'/'`` if they want to be agnostic to the operating system.

The ``filename_pattern`` option is also useful if you want to build only a
subset of the examples. For example, you may
want to build only one example so that you can link it in the documentation. In that case,
you would do::
want to build only one example so that you can link it in the documentation.
In that case, you would do::

sphinx_gallery_conf = {
...
'filename_pattern': r'plot_awesome_example\.py',
}

Here, one should escape the dot ``r'\.'`` as otherwise python `regular expressions`_ matches any character. Nevertheless, as
one is targeting a specific file, it would match the dot in the filename even without this escape character.
Here, one should escape the dot ``r'\.'`` as otherwise python
`regular expressions`_ matches any character. Nevertheless, as
one is targeting a specific file, it would match the dot in the filename even
without this escape character.

.. note::
Sphinx-Gallery only re-runs examples that have changed (according to their
Expand All @@ -173,20 +175,21 @@ Similarly, to build only examples in a specific directory, you can do::
'filename_pattern': '/directory/plot_',
}

Alternatively, you can skip executing some examples. For example, to skip building examples
starting with ``plot_long_examples_``, you would do::
Alternatively, you can skip executing some examples. For example, to skip
building examples starting with ``plot_long_examples_``, you would do::

sphinx_gallery_conf = {
...
'filename_pattern': '/plot_(?!long_examples)',
}

As the patterns are parsed as `regular expressions`_, users are advised to consult the
`regular expressions`_ module for more details.
As the patterns are parsed as `regular expressions`_, users are advised to
consult the `regular expressions`_ module for more details.

.. note::
Remember that Sphinx allows overriding ``conf.py`` values from the command
line, so you can for example build a single example directly via something like:
line, so you can for example build a single example directly via something
like:

.. code-block:: console

Expand Down Expand Up @@ -950,7 +953,8 @@ Generate Binder links for gallery notebooks (experimental)

Sphinx-Gallery automatically generates Jupyter notebooks for any
examples built with the gallery. `Binder <https://mybinder.org>`_ makes it
possible to create interactive GitHub repositories that connect to cloud resources.
possible to create interactive GitHub repositories that connect to cloud
resources.

If you host your documentation on a GitHub repository, it is possible to
auto-generate a Binder link for each notebook. Clicking this link will
Expand Down Expand Up @@ -983,12 +987,17 @@ dictionary following the pattern below::
}
}

If a Sphinx-Gallery configuration for Binder is discovered, the following extra things will happen:

1. The dependency files specified in ``dependencies`` will be copied to a ``binder/`` folder in your built documentation.
2. The built Jupyter Notebooks from the documentation will be copied to a folder called ``<notebooks_dir/>`` at the root of
your built documentation (they will follow the same folder hierarchy within the notebooks directory folder.
3. The rST output of each Sphinx-Gallery example will now have a ``launch binder`` button in it.
If a Sphinx-Gallery configuration for Binder is discovered, the following extra
things will happen:

1. The dependency files specified in ``dependencies`` will be copied to a
``binder/`` folder in your built documentation.
2. The built Jupyter Notebooks from the documentation will be copied to a
folder called ``<notebooks_dir/>`` at the root of
your built documentation (they will follow the same folder hierarchy within
the notebooks directory folder.
3. The rST output of each Sphinx-Gallery example will now have a
``launch binder`` button in it.
4. That button will point to a binder link with the following structure

.. code-block:: html
Expand All @@ -1003,23 +1012,29 @@ repo (type: string)
The GitHub repository where your documentation is stored.
ref (type: string)
A reference to the version of your repository where your documentation exists.
For example, if your built documentation is stored on a ``gh-pages`` branch, then this field
should be set to ``gh-pages``.
For example, if your built documentation is stored on a ``gh-pages`` branch,
then this field should be set to ``gh-pages``.
binderhub_url (type: string)
The full URL to a BinderHub deployment where you want your examples to run. One
public BinderHub deployment is at ``https://mybinder.org``, though if you (and your users) have access to
another, this can be configured with this field.
The full URL to a BinderHub deployment where you want your examples to run.
One public BinderHub deployment is at ``https://mybinder.org``, though if you
(and your users) have access to another, this can be configured with this
field.
dependencies (type: list)
A list of paths (relative to ``conf.py``) to dependency files that Binder uses to infer the environment needed
to run your examples. For example, a ``requirements.txt`` file. These will be copied into a folder
called ``binder/`` in your built documentation folder. For a list of all the possible dependency files
you can use, see `the Binder configuration documentation <https://mybinder.readthedocs.io/en/latest/config_files.html#config-files>`_.
A list of paths (relative to ``conf.py``) to dependency files that Binder uses
to infer the environment needed to run your examples. For example, a
``requirements.txt`` file. These will be copied into a folder called
``binder/`` in your built documentation folder. For a list of all the possible
dependency files you can use, see `the Binder configuration documentation
<https://mybinder.readthedocs.io/en/latest/config_files.html#config-files>`_.
filepath_prefix (type: string | None, default: ``None``)
A prefix to append to the filepath in the Binder links. You should use this if you will store your built
documentation in a sub-folder of a repository, instead of in the root.
A prefix to append to the filepath in the Binder links. You should use this if
you will store your built documentation in a sub-folder of a repository,
instead of in the root.
notebooks_dir (type: string, default: ``notebooks``)
The name of a folder where the built Jupyter notebooks will be copied. This ensures that all the notebooks are
in one place (though they retain their folder hierarchy) in case you'd like users to browse multiple notebook examples in one session.
The name of a folder where the built Jupyter notebooks will be copied. This
ensures that all the notebooks are in one place (though they retain their
folder hierarchy) in case you'd like users to browse multiple notebook
examples in one session.
use_jupyter_lab (type: bool, default: ``False``)
Whether the default interface activated by the Binder link will be for
Jupyter Lab or the classic Jupyter Notebook interface.
Expand Down Expand Up @@ -1142,9 +1157,9 @@ This is converted to html by the custom directive as::
This leads to a larger website, but clients that support the ``srcset`` tag will only
download the appropriate-sized images.

Note that the ``.. image-sg`` directive currently ignores other ``.. image`` directive
tags like ``width``, ``height``, and ``align``. It also only works with the *html* and
*latex* builders.
Note that the ``.. image-sg`` directive currently ignores other ``.. image``
directive tags like ``width``, ``height``, and ``align``. It also only works
with the *html* and *latex* builders.

.. _image_scrapers:

Expand Down Expand Up @@ -1381,8 +1396,8 @@ by including in your ``Makefile``:
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

Remember that for ``Makefile`` white space is significant and the indentation are tabs
and not spaces.
Remember that for ``Makefile`` white space is significant and the indentation
are tabs and not spaces.

Alternatively, you can add the ``abort_on_example_error`` option to
the ``sphinx_gallery_conf`` dictionary inside your ``conf.py``
Expand Down Expand Up 9E88 @@ -1425,7 +1440,9 @@ the example script.
Never fail the build on error
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sphinx-Gallery can be configured to only log warnings when examples fail. This means that sphinx will only exit with a non-zero exit code if the ``-W`` flag is passed to ``sphinx-build``. This can be enabled by setting::
Sphinx-Gallery can be configured to only log warnings when examples fail.
This means that sphinx will only exit with a non-zero exit code if the ``-W``
flag is passed to ``sphinx-build``. This can be enabled by setting::

sphinx_gallery_conf = {
...
Expand Down
2 changes: 1 addition & 1 deletion sphinx_gallery/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
import os
# dev versions should have "dev" in them, stable should not.
# doc/conf.py makes use of this to set the version drop-down.
__version__ = '0.11.0.dev0'
__version__ = '0.10.1'


def glr_path_static():
Expand Down
0