diff --git a/README.rst b/README.rst index 13633528d..eb6a17769 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,6 @@ -================================= -Getting Started to Sphinx-Gallery -================================= +=================================== +Getting Started with Sphinx-Gallery +=================================== .. image:: https://travis-ci.org/sphinx-gallery/sphinx-gallery.svg?branch=master :target: https://travis-ci.org/sphinx-gallery/sphinx-gallery @@ -34,11 +34,14 @@ Who uses Sphinx-Gallery * `scikit-image `_ * `Astropy `_ * `SunPy `_ +* `PySurfer `_ Getting the package =================== -You can do a direct install via pip by using:: +You can do a direct install via pip by using: + +.. code-block:: bash $ pip install sphinx-gallery @@ -64,7 +67,9 @@ You can get the latest development source from our `Github repository You will also need to install the dependencies listed above and `pytest` -To install everything do:: +To install everything do: + +.. code-block:: bash $ git clone https://github.com/sphinx-gallery/sphinx-gallery $ cd sphinx-gallery @@ -103,9 +108,7 @@ structure you get from executing ``sphinx-quickstart``. To get Sphinx-Gallery into your project we have to extend the Sphinx -``doc/conf.py`` file with: - -.. code-block:: python +``doc/conf.py`` file with:: extensions = [ ... @@ -117,9 +120,7 @@ This is to load Sphinx-Gallery as one of your extensions, the ellipsis Now to declare your project structure, we add a configuration dictionary for Sphinx-Gallery. The examples directory ``../examples`` -is declared with a relative path from the ``conf.py`` file location. - -.. code-block:: python +is declared with a relative path from the ``conf.py`` file location:: sphinx_gallery_conf = { # path to your examples scripts @@ -157,7 +158,9 @@ files. Building the documentation locally ---------------------------------- -In your sphinx documentation directory, ``doc`` execute:: +In your sphinx documentation directory, ``doc`` execute: + +.. code-block:: bash $ make html @@ -165,7 +168,9 @@ This will start the build of your complete documentation including the examples gallery. Once documentation is build, our extension will have generated an ``auto_examples`` directory and populated it with rst files containing the gallery and each example. Sphinx gives this files its regular processing and you can enjoy your -generated gallery under the same path. That means you will find the gallery in the path:: +generated gallery under the same path. That means you will find the gallery in the path: + +.. code-block:: bash _build/html/auto_examples/index.html @@ -181,7 +186,9 @@ Extending your Makefile ----------------------- Once your gallery is working you might need remove completely all generated files by sphinx-gallery to have a clean build, or you might want to build the gallery without -running the examples files. For this you need to extend your ``Makefile`` with:: +running the examples files. For this you need to extend your ``Makefile`` with: + +.. code-block:: bash clean: rm -rf $(BUILDDIR)/* diff --git a/doc/advanced_configuration.rst b/doc/advanced_configuration.rst index 4a71add2e..4a7d863f8 100644 --- a/doc/advanced_configuration.rst +++ b/doc/advanced_configuration.rst @@ -1,29 +1,67 @@ +============= +Configuration +============= + +Configuration and customization of sphinx-gallery is done primarily with a +dictionary specified in your ``conf.py`` file. A list of the possible +keys are listed :ref:`below ` and explained in +greater detail in subsequent sections. + +.. _list_of_options: + +List of config options ====================== -Advanced Configuration -====================== -Here are the personal configurations that you can modify within Sphinx-Gallery. +Most sphinx-gallery configuration options are set in the Sphinx ``conf.py`` +file: + +- ``examples_dirs`` and ``gallery_dirs`` (:ref:`multiple_galleries_config`) +- ``filename_pattern`` (:ref:`build_pattern`) +- ``subsection_order`` (:ref:`sub_gallery_order`) +- ``reference_url`` (:ref:`link_to_documentation`) +- ``backreferences_dir`` and ``doc_module`` (:ref:`references_to_examples`) +- ``default_thumb_file`` (:ref:`custom_default_thumb`) +- ``line_numbers`` (:ref:`adding_line_numbers`) +- ``download_section_examples`` (:ref:`disable_joint_download`) +- ``plot_gallery`` (:ref:`without_execution`) +- ``find_mayavi_figures`` (:ref:`find_mayavi`) +- ``abort_on_example_error`` (:ref:`abort_on_first`) +- ``expected_failing_examples`` (:ref:`dont_fail_exit`) + +Some options can also be set or overridden on a file-by-file basis: + +- ``# sphinx_gallery_line_numbers`` (:ref:`adding_line_numbers`) +- ``# sphinx_gallery_thumbnail_number`` (:ref:`choosing_thumbnail`) + +Some options can be set during the build execution step, e.g. using a Makefile: + +- ``make html-noplot`` (:ref:`without_execution`) +- ``make html_abort_on_example_error`` (:ref:`abort_on_first`) + +And some things can be tweaked directly in CSS: + +- ``.sphx-glr-thumbcontainer`` (:ref:`setting_thumbnail_size`) + .. _multiple_galleries_config: -Manage Multiple galleries -========================= +Managing multiple galleries +=========================== Sphinx-Gallery only supports up to sub-folder level in its gallery directories. This might be a limitation for you. Or you might want to have separate galleries for different purposes, an examples gallery and a tutorials gallery. For this you use in your Sphinx ``conf.py`` file a list of directories in -the sphinx configuration dictionary: - -.. code-block:: python +the sphinx configuration dictionary:: sphinx_gallery_conf = { - 'examples_dirs' : ['../examples', '../tutorials'], - 'gallery_dirs' : ['auto_examples', 'tutorials'], + 'examples_dirs': ['../examples', '../tutorials'], + 'gallery_dirs': ['auto_examples', 'tutorials'], } Keep in mind that both lists have to be of the same length. + .. _build_pattern: Building examples matching a pattern @@ -31,12 +69,10 @@ Building examples matching a pattern By default, Sphinx-Gallery execute only examples beginning with ``plot``. However, if this naming convention does not suit your project, you can modify this pattern -in your Sphinx ``conf.py``. For example: - -.. code-block:: python +in your Sphinx ``conf.py``. For example:: sphinx_gallery_conf = { - 'filename_pattern' : '/plot_compute_' + 'filename_pattern': '/plot_compute_', } will build all examples starting with ``plot_compute_``. The key ``filename_pattern`` accepts @@ -46,49 +82,42 @@ they want to be agnostic to the operating system. This 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: - -.. code-block:: python +you would do:: sphinx_gallery_conf = { - 'filename_pattern' : 'plot_awesome_example.py' + 'filename_pattern': 'plot_awesome_example.py', } Here, one should escape the dot ``'\.'`` as otherwise python `regular expressions`_ matches any character. Nevertheless, as one is targeting a specific file, it is most certainly going to match the dot in the filename. -Similarly, to build only examples in a specific directory, you can do: - -.. code-block:: python +Similarly, to build only examples in a specific directory, you can do:: sphinx_gallery_conf = { - 'filename_pattern' : '/directory/plot_' + 'filename_pattern': '/directory/plot_', } Alternatively, you can skip some examples. For example, to skip building examples -starting with ``plot_long_examples_``, you would do: - -.. code-block:: python +starting with ``plot_long_examples_``, you would do:: sphinx_gallery_conf = { - 'filename_pattern' : '/plot_(?!long_examples)' + '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. + .. _sub_gallery_order: -Sorting the subsections inside a gallery -======================================== +Sorting gallery subsections +=========================== Gallery subsections are sorted by default alphabetically by their folder name, and as such you can always organize them by changing your folder names. An alternative option is to use a sortkey to organize those subsections. We provide an explicit order sortkey where you have to define -the order of all subfolders in your galleries. - -.. code-block:: python +the order of all subfolders in your galleries:: from sphinx_gallery.sorting import ExplicitOrder sphinx_gallery_conf = { @@ -133,29 +162,27 @@ Have a look at this in full action in our example :ref:`sphx_glr_auto_examples_plot_gallery_version.py`. To make this work in your documentation you need to include to the configuration -dictionary within your Sphinx ``conf.py`` file : - -.. code-block:: python +dictionary within your Sphinx ``conf.py`` file:: sphinx_gallery_conf = { - 'reference_url': { + 'reference_url': { # The module you locally document uses a None 'sphinx_gallery': None, # External python modules use their documentation websites 'matplotlib': 'https://matplotlib.org', - 'numpy': 'https://docs.scipy.org/doc/numpy'} + 'numpy': 'https://docs.scipy.org/doc/numpy'}, } .. _references_to_examples: -References to examples (backreferences) -======================================= +Adding references to examples +============================= Sphinx-Gallery enables you, when documenting your modules, to reference to the examples that use a particular function. For example -if we are documenting the :data:`numpy.exp` function its possible to embed +if we are documenting the :func:`numpy.exp` function its possible to embed a small gallery of examples that is specific to this function and looks like this: @@ -165,11 +192,8 @@ looks like this:
- For such behavior to be available, you have to activate it in your -Sphinx-Gallery configuration ``conf.py`` file with: - -.. code-block:: python +Sphinx-Gallery configuration ``conf.py`` file with:: sphinx_gallery_conf = { # directory where function granular galleries are stored @@ -202,16 +226,14 @@ is in the same directory as ``conf.py``) we directly use the path declared in ``backreferences_dir`` followed by the function whose examples we want to show and the file has the ``.examples`` extension. -Auto documenting your API with links to examples ------------------------------------------------- +Auto-documenting your API with links to examples +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The previous feature can be automated for all your modules combining it with the standard sphinx extensions `autodoc `_ and `autosummary `_. First enable them in your -``conf.py`` extensions list. - -.. code-block:: python +``conf.py`` extensions list:: import sphinx_gallery extensions = [ @@ -262,31 +284,68 @@ configuration option setup for Sphinx-Gallery. :linenos: -Using a custom default thumbnail image -====================================== +.. _custom_default_thumb: + +Using a custom default thumbnail +================================ In case you want to use your own image for the thumbnail of examples that do not generate any plot, you can specify it by editing your Sphinx ``conf.py`` file. You need to add to the configuration dictionary a key called -`default_thumb_file`. For example: +`default_thumb_file`. For example:: -.. code-block:: python + sphinx_gallery_conf = { + 'default_thumb_file': 'path/to/thumb/file.png', + } + + +.. _adding_line_numbers: + +Adding line numbers to examples +=============================== + +Line numbers can be displayed in listings by adding the global ``line_numbers`` +setting:: sphinx_gallery_conf = { - 'default_thumb_file' : 'path/to/thumb/file.png'}} + 'line_numbers': True, + } + +or by adding a comment to the example script, which overrides any global +setting:: + + # sphinx_gallery_line_numbers = True + +Note that for Sphinx < 1.3, the line numbers will not be consistent with the +original file. + + +.. _disable_joint_download: +Disabling joint download of scripts +=================================== -Choosing the thumbnail image from multiple figures -================================================== +By default Sphinx-Gallery prepares zip files of all python scripts and +all Jupyter notebooks for each gallery section and makes them +available for download at the end of each section. To disable this +behavior add to the configuration dictionary in your ``conf.py`` file:: + + sphinx_gallery_conf = { + 'download_section_examples': False, + } + + +.. _choosing_thumbnail: + +Choosing the thumbnail image +============================ For examples that generate multiple figures, the default behavior will use the first figure created in each as the thumbnail image displayed in the gallery. To change the thumbnail image to a figure generated later in an example script, add a comment to the example script to specify the number of the figure you would like to use as the thumbnail. For example, -to use the 2nd figure created as the thumbnail: - -.. code-block:: python +to use the 2nd figure created as the thumbnail:: # sphinx_gallery_thumbnail_number = 2 @@ -294,8 +353,11 @@ The default behavior is ``sphinx_gallery_thumbnail_number = 1``. See :ref:`sphx_glr_auto_examples_plot_choose_thumbnail.py` for an example of this functionality. -Build the Gallery without executing the examples -================================================ + +.. _without_execution: + +Building without executing examples +=================================== Sphinx-Gallery can parse all your examples and build the gallery without executing any of the scripts. This is just for speed @@ -313,32 +375,29 @@ Remember that for ``Makefile`` white space is significant and the indentation ar and not spaces. Alternatively, you can add the ``plot_gallery`` option to the -``sphinx_gallery_conf`` dictionary inside your ``conf.py`` -configuration file to have it as a default. The highest precedence is -always given to the `-D` flag of the ``sphinx-build`` command. - - -Adding line numbers to example listings -======================================= - -Line numbers can be displayed in listings by adding the global ``line_numbers`` -setting: - -.. code-block:: python +``sphinx_gallery_conf`` dictionary inside your ``conf.py`` to have it as +a default:: sphinx_gallery_conf = { - 'line_numbers': True + 'plot_gallery': False, } -or by adding a comment to the example script, which overrides any global -setting: +The highest precedence is always given to the `-D` flag of the +``sphinx-build`` command. -.. code-block:: python - # sphinx_gallery_line_numbers = True +.. _find_mayavi: -Note that for Sphinx < 1.3, the line numbers will not be consistent with the -original file. +Finding Mayavi figures +====================== +By default, Sphinx-gallery will only look for :mod:`matplotlib.pyplot` figures +when building. However, extracting figures generated by :mod:`mayavi.mlab` is +also supported. To enable this feature, you can do:: + + + sphinx_gallery_conf = { + 'find_mayavi_figures': True, + } Dealing with failing Gallery example scripts @@ -352,7 +411,7 @@ thumbnail. That allows you to find with a quick glance of the gallery which examples failed. Broken examples remain accessible in the html view of the gallery and the traceback message is written for the failing code block. Refer to example -:ref:`sphx_glr_auto_examples_plot_raise.py` to view the default +:ref:`sphx_glr_auto_examples_no_output_plot_raise.py` to view the default behavior. The build is also failed exiting with code 1 and giving you a summary @@ -362,6 +421,8 @@ easily. There are some additional options at your hand to deal with broken examples. +.. _abort_on_first: + Abort build on first fail ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -381,9 +442,17 @@ and not spaces. Alternatively, you can add the ``abort_on_example_error`` option to the ``sphinx_gallery_conf`` dictionary inside your ``conf.py`` -configuration file to have it as a default. The highest precedence is -always given to the `-D` flag of the ``sphinx-build`` command. +configuration file to have it as a default:: + + sphinx_gallery_conf = { + 'abort_on_example_error': True, + } + + +The highest precedence is always given to the `-D` flag of +the ``sphinx-build`` command. +.. _dont_fail_exit: Don't fail the build on exit ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -392,10 +461,7 @@ It might be the case that you want to keep the gallery even with failed examples. Thus you can configure Sphinx-Gallery to allow certain examples to fail and still exit with a 0 exit code. For this you need to list all the examples you want to allow to fail during -build. Change your `conf.py` accordingly: - - -.. code-block:: python +build. Change your `conf.py` accordingly:: sphinx_gallery_conf = { ... @@ -407,4 +473,30 @@ keep in mind to specify the full relative path from your `conf.py` to the example script. +.. _setting_thumbnail_size: + +Setting gallery thumbnail size +============================== + +The gallery uses various CSS classes in the gallery. For example, to use +images that are at most 250x250px, you can modify the default CSS +with something like: + +.. code-block:: css + + .sphx-glr-thumbcontainer { + min-height: 300px; + } + .sphx-glr-thumbcontainer .figure { + width: 250px; + } + .sphx-glr-thumbcontainer img { + max-height: 250px; + width: 250px; + } + .sphx-glr-thumbcontainer a.internal { + padding: 210px + } + + .. _regular expressions: https://docs.python.org/2/library/re.html diff --git a/doc/conf.py b/doc/conf.py index 7b8c85fb0..eaa5dff23 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -84,6 +84,11 @@ # directories to ignore when looking for source files. exclude_patterns = ['_build'] +# See warnings about bad links +nitpicky = True +# we intentionally link outside images +suppress_warnings = ['image.nonlocal_uri'] + # The reST default role (used for this markup: `text`) to use for all # documents. #default_role = None @@ -298,6 +303,7 @@ def setup(app): 'numpy': ('https://docs.scipy.org/doc/numpy/', None), 'scipy': ('https://docs.scipy.org/doc/scipy/reference', None), 'matplotlib': ('https://matplotlib.org/', None), + 'mayavi': ('http://docs.enthought.com/mayavi/mayavi', None), } from sphinx_gallery.sorting import ExplicitOrder diff --git a/doc/getting_started.rst b/doc/getting_started.rst index c57130c0e..f5413ad67 100644 --- a/doc/getting_started.rst +++ b/doc/getting_started.rst @@ -1,6 +1,5 @@ .. include:: ../README.rst - Know your Gallery files ======================= @@ -21,16 +20,3 @@ its reference ``:ref:`sphx_glr_auto_examples_plot_gallery_version.py```. The image it generated has the name ``sphx_glr_plot_gallery_version_thumb.png`` and its thumbnail is ``sphx_glr_plot_gallery_version_thumb.png`` - -Disable joint download of all gallery scripts ---------------------------------------------- - -By default Sphinx-Gallery prepares zip files of all python scripts and -all Jupyter notebooks for each gallery section and makes them -available for download at the end of each section. To disable this -behavior add to the configuration dictionary in your ``conf.py`` file - -.. code-block:: python - - sphinx_gallery_conf = { - 'download_section_examples' : False}