[Python-modules-commits] [sphinx-gallery] 01/02: Import Upstream version 0.1.13
Sandro Tosi
morph at moszumanska.debian.org
Sun Nov 26 21:57:40 UTC 2017
This is an automated email from the git hooks/post-receive script.
morph pushed a commit to branch master
in repository sphinx-gallery.
commit 54de2484d26e40b85f72c3193396a6de664ce000
Author: Sandro Tosi <morph at debian.org>
Date: Sun Nov 26 16:57:18 2017 -0500
Import Upstream version 0.1.13
---
.gitignore | 69 +++
.travis.yml | 86 +++
CHANGES.rst | 346 +++++++++++
LICENSE | 27 +
MANIFEST.in | 2 +
README.rst | 203 +++++++
appveyor.yml | 45 ++
bin/copy_sphinxgallery.sh | 11 +
bin/sphx_glr_python_to_jupyter.py | 20 +
circle.yml | 45 ++
doc/Makefile | 203 +++++++
doc/_static/theme_override.css | 15 +
doc/_templates/breadcrumbs.html | 27 +
doc/_templates/module.rst | 54 ++
doc/advanced_configuration.rst | 575 ++++++++++++++++++
doc/changes.rst | 2 +
doc/conf.py | 344 +++++++++++
doc/faq.rst | 25 +
doc/getting_started.rst | 22 +
doc/index.rst | 87 +++
doc/make.bat | 242 ++++++++
doc/reference.rst | 30 +
doc/syntax.rst | 40 ++
doc/utils.rst | 27 +
docs_deploy.sh | 40 ++
examples/README.txt | 12 +
examples/no_output/README.txt | 9 +
examples/no_output/just_code.py | 14 +
examples/no_output/plot_raise.py | 35 ++
examples/no_output/plot_strings.py | 20 +
examples/no_output/plot_syntaxerror.py | 14 +
examples/plot_choose_thumbnail.py | 39 ++
examples/plot_colors.py | 41 ++
examples/plot_exp.py | 35 ++
examples/plot_function_identifier.py | 40 ++
examples/plot_gallery_version.py | 52 ++
examples/plot_quantum.py | 66 +++
examples/plot_seaborn.py | 29 +
examples/plot_sys_argv.py | 15 +
examples/sin_func/README.txt | 7 +
examples/sin_func/plot_sin.py | 40 ++
examples/sin_func/plot_sin_black_background.py | 32 +
mayavi_examples/README.txt | 12 +
mayavi_examples/plot_3d.py | 35 ++
requirements.txt | 5 +
setup.cfg | 12 +
setup.py | 46 ++
sphinx_gallery/__init__.py | 12 +
sphinx_gallery/_static/broken_example.png | Bin 0 -> 21404 bytes
sphinx_gallery/_static/broken_stamp.svg | 90 +++
sphinx_gallery/_static/gallery.css | 192 ++++++
sphinx_gallery/_static/no_image.png | Bin 0 -> 4315 bytes
sphinx_gallery/backreferences.py | 217 +++++++
sphinx_gallery/docs_resolv.py | 392 ++++++++++++
sphinx_gallery/downloads.py | 124 ++++
sphinx_gallery/gen_gallery.py | 365 ++++++++++++
sphinx_gallery/gen_rst.py | 656 +++++++++++++++++++++
sphinx_gallery/notebook.py | 193 ++++++
sphinx_gallery/py_source_parser.py | 157 +++++
sphinx_gallery/sorting.py | 119 ++++
sphinx_gallery/sphinx_compatibility.py | 77 +++
sphinx_gallery/tests/__init__.py | 0
sphinx_gallery/tests/conftest.py | 70 +++
sphinx_gallery/tests/reference_parse.txt | 33 ++
sphinx_gallery/tests/test_backreferences.py | 92 +++
sphinx_gallery/tests/test_docs_resolv.py | 77 +++
sphinx_gallery/tests/test_full.py | 54 ++
sphinx_gallery/tests/test_gen_gallery.py | 232 ++++++++
sphinx_gallery/tests/test_gen_rst.py | 327 ++++++++++
sphinx_gallery/tests/test_notebook.py | 116 ++++
sphinx_gallery/tests/test_sorting.py | 32 +
sphinx_gallery/tests/test_sphinx_compatibility.py | 77 +++
sphinx_gallery/tests/testconfs/src/README.txt | 2 +
sphinx_gallery/tests/testconfs/src/plot_1.py | 11 +
sphinx_gallery/tests/testconfs/src/plot_2.py | 9 +
sphinx_gallery/tests/testconfs/src/plot_3.py | 14 +
sphinx_gallery/tests/tinybuild/Makefile | 18 +
.../tests/tinybuild/_templates/module.rst | 54 ++
sphinx_gallery/tests/tinybuild/conf.py | 30 +
sphinx_gallery/tests/tinybuild/examples/README.txt | 4 +
.../tests/tinybuild/examples/plot_numpy_scipy.py | 16 +
sphinx_gallery/tests/tinybuild/index.rst | 35 ++
sphinx_gallery/utils.py | 38 ++
tutorials/README.txt | 13 +
tutorials/plot_notebook.py | 113 ++++
tutorials/plot_parse.py | 102 ++++
tutorials/seaborn/README.txt | 4 +
tutorials/seaborn/plot_seaborn_notebook.py | 36 ++
88 files changed, 7400 insertions(+)
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..29fb206
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,69 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+.eggs
+
+# PyInstaller
+# Usually these files are written by a python script from a template
+# before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.cache
+nosetests.xml
+coverage.xml
+*.orig
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+doc/_build/
+doc/auto_examples
+doc/auto_mayavi_examples
+doc/tutorials/
+doc/gen_modules/
+
+# Test builds
+sphinx_gallery/tests/tinybuild/gen_modules/
+sphinx_gallery/tests/tinybuild/auto_examples/
+sphinx_gallery/tests/tinybuild/_build/
+
+# PyBuilder
+target/
+
+# General temporary files to ignore
+*.swp
+*.swo
diff --git a/.travis.yml b/.travis.yml
new file mode 100644
index 0000000..3a71d99
--- /dev/null
+++ b/.travis.yml
@@ -0,0 +1,86 @@
+language: python
+sudo: false
+addons:
+ apt:
+ packages:
+ - xvfb # For mayavi headless
+
+virtualenv:
+ system_site_packages: true
+
+matrix:
+ include:
+ - os: linux
+ env: DISTRIB="ubuntu" PYTHON_VERSION="2.7"
+ addons:
+ apt:
+ packages:
+ - python-numpy
+ - python-matplotlib
+ - python-scipy
+ - python-pip
+ - python-coverage
+ - cython
+ - python-pandas
+ # This environment tests is for mayavi
+ - os: linux
+ env: DISTRIB="conda" PYTHON_VERSION="2.7"
+ # This environment tests the Python 3 versions
+ - os: linux
+ env: DISTRIB="conda" PYTHON_VERSION="3.4"
+ - os: linux
+ env: DISTRIB="conda" PYTHON_VERSION="3.5"
+ - os: linux
+ env: DISTRIB="conda" PYTHON_VERSION="3.6"
+ - os: linux
+ dist: trusty
+ python: 'nightly'
+ allow_failures:
+ - python: "nightly"
+
+before_install:
+ - if [ "$DISTRIB" == "conda" ]; then
+ wget https://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh;
+ chmod +x miniconda.sh;
+ ./miniconda.sh -b;
+ export PATH=/home/travis/miniconda2/bin:$PATH;
+ conda update --yes conda;
+ fi
+
+install:
+ # force no mkl because mayavi requires old version of numpy
+ # which then crashes with pandas and seaborn
+ - if [ "$DISTRIB" == "conda" ]; then
+ conda create --yes -n testenv python=$PYTHON_VERSION pip nomkl numpy
+ setuptools matplotlib pillow sphinx pytest pytest-cov coverage seaborn;
+ source activate testenv;
+ if [ "$PYTHON_VERSION" == "2.7" ]; then
+ conda install --yes mayavi;
+ fi;
+ fi;
+ - |
+ if [ "$DISTRIB" == "ubuntu" ]; then
+ # Use a separate virtual environment that the one provided by
+ # Travis because it contains numpy and we want to use numpy
+ # from apt-get
+ deactivate
+ virtualenv --system-site-packages testvenv
+ source testvenv/bin/activate
+ pip install -r requirements.txt
+ pip install seaborn sphinx==1.4.9 pytest pytest-cov
+ fi
+ - python setup.py install
+
+# To test the mayavi environment follow the instructions at
+# https://docs.travis-ci.com/user/gui-and-headless-browsers/#Using-xvfb-to-Run-Tests-That-Require-a-GUI
+before_script:
+ - "export DISPLAY=:99.0"
+ - "sh -e /etc/init.d/xvfb start"
+ - sleep 3 # give xvfb some time to start
+
+script:
+ - python setup.py test
+ - pytest sphinx_gallery
+ - cd doc
+ - make html-noplot
+ - make html -j 2
diff --git a/CHANGES.rst b/CHANGES.rst
new file mode 100644
index 0000000..4cc523b
--- /dev/null
+++ b/CHANGES.rst
@@ -0,0 +1,346 @@
+Change Log
+==========
+
+git master
+----------
+
+v0.1.12
+-------
+
+New features
+''''''''''''
+
+* Added ``min_reported_time`` configurable. For examples that run faster than
+ that threshold (in seconds), the execution time is not reported.
+* Add thumbnail_size option `#283 <https://github.com/sphinx-gallery/sphinx-gallery/pull/283>`_
+* Use intersphinx for all function reference resolution `#296 <https://github.com/sphinx-gallery/sphinx-gallery/pull/296>`_
+* Sphinx only directive for downloads `#298 <https://github.com/sphinx-gallery/sphinx-gallery/pull/298>`_
+* Allow sorting subsection files `#281 <https://github.com/sphinx-gallery/sphinx-gallery/pull/281>`_
+
+Bug Fixes
+'''''''''
+
+* Crasher in doc_resolv, in js_index.loads `#287 <https://github.com/sphinx-gallery/sphinx-gallery/issues/287>`_
+* Fix gzip/BytesIO error `#293 <https://github.com/sphinx-gallery/sphinx-gallery/pull/293>`_
+* Deactivate virtualenv provided by Travis `#294 <https://github.com/sphinx-gallery/sphinx-gallery/pull/294>`_
+
+Developer changes
+'''''''''''''''''
+
+* Push the docs from Circle CI into github `#268 <https://github.com/sphinx-gallery/sphinx-gallery/pull/268>`_
+* Report version to sphinx. `#292 <https://github.com/sphinx-gallery/sphinx-gallery/pull/292>`_
+* Minor changes to log format. `#285 <https://github.com/sphinx-gallery/sphinx-gallery/pull/285>`_ and `#291 <https://github.com/sphinx-gallery/sphinx-gallery/pull/291>`_
+
+v0.1.12
+-------
+
+New features
+''''''''''''
+
+* Implement a explicit order sortkey to specify the subsection's order
+ within a gallery. Refer to discussion in
+ `#37 <https://github.com/sphinx-gallery/sphinx-gallery/issues/37>`_,
+ `#233 <https://github.com/sphinx-gallery/sphinx-gallery/pull/233>`_ and
+ `#234 <https://github.com/sphinx-gallery/sphinx-gallery/pull/234>`_
+* Cleanup console output during build
+ `#250 <https://github.com/sphinx-gallery/sphinx-gallery/pull/250>`_
+* New configuration Test
+ `#225 <https://github.com/sphinx-gallery/sphinx-gallery/pull/225>`_
+
+Bug Fixes
+'''''''''
+
+* Reset ``sys.argv`` before running each example. See
+ `#252 <https://github.com/sphinx-gallery/sphinx-gallery/pull/252>`_
+ for more details.
+* Correctly re-raise errors in doc resolver. See
+ `#264 <https://github.com/sphinx-gallery/sphinx-gallery/pull/264>`_.
+* Allow and use https links where possible
+ `#258 <https://github.com/sphinx-gallery/sphinx-gallery/pull/258>`_.
+* Escape tooltips for any HTML special characters.
+ `#249 <https://github.com/sphinx-gallery/sphinx-gallery/pull/249>`_
+
+Documentation
+'''''''''''''''
+
+* Update link to numpy to point to latest
+ `#271 <https://github.com/sphinx-gallery/sphinx-gallery/pull/271>`_
+* Added documentation dependencies.
+ `#267 <https://github.com/sphinx-gallery/sphinx-gallery/pull/267>`_
+
+v0.1.11
+-------
+
+Documentation
+'''''''''''''''
+
+* Frequently Asked Questions added to Documentation. Why `__file__` is
+ not defined?
+
+Bug Fixed
+'''''''''
+
+* Changed attribute name of Sphinx `app` object in `#242
+ <https://github.com/sphinx-gallery/sphinx-gallery/issues/242>`_
+
+v0.1.10
+-------
+
+Bug Fixed
+'''''''''
+
+* Fix image path handling bug introduced in #218
+
+v0.1.9
+------
+
+Incompatible Changes
+''''''''''''''''''''
+
+* Sphinx Gallery's example back-references are deactivated by
+ default. Now it is users responsibility to turn them on and set the
+ directory where to store the files. See discussion in `#126
+ <https://github.com/sphinx-gallery/sphinx-gallery/issues/126>`_ and
+ pull request `#151
+ <https://github.com/sphinx-gallery/sphinx-gallery/issues/151>`_.
+
+Bug Fixed
+'''''''''
+
+* Fix download zip files path in windows builds. See `#218 <https://github.com/sphinx-gallery/sphinx-gallery/pull/218>`_
+* Fix embedded missing link. See `#214 <https://github.com/sphinx-gallery/sphinx-gallery/pull/214>`_
+
+Developer changes
+'''''''''''''''''
+
+* Move testing to py.test
+* Include link to github repository in documentation
+
+v0.1.8
+------
+
+New features
+''''''''''''
+
+* Drop styling in codelinks tooltip. Replaced for title attribute which is managed by the browser.
+* Gallery output is shorter when embedding links
+* Circle CI testing
+
+Bug Fixes
+'''''''''
+
+* Sphinx-Gallery build even if examples have Syntax errors. See `#177 <https://github.com/sphinx-gallery/sphinx-gallery/pull/177>`_
+* Sphinx-Gallery can now build by directly calling sphinx-build from
+ any path, no explicit need to run the Makefile from the sources
+ directory. See `#190 <https://github.com/sphinx-gallery/sphinx-gallery/pull/190>`_
+ for more details.
+
+v0.1.7
+------
+
+Bug Fixes
+'''''''''
+
+* Released Sphinx 1.5 has new naming convention for auto generated
+ files and breaks Sphinx-Gallery documentation scanner. Fixed in
+ `#178 <https://github.com/sphinx-gallery/sphinx-gallery/pull/178>`_,
+ work for linking to documentation generated with Sphinx<1.5 and for
+ new docs post 1.5
+* Code links tooltip are now left aligned with code
+
+New features
+''''''''''''
+
+* Development support of Sphinx-Gallery on Windows `#179
+ <https://github.com/sphinx-gallery/sphinx-gallery/pull/179>`_ & `#182
+ <https://github.com/sphinx-gallery/sphinx-gallery/pull/182>`_
+
+v0.1.6
+----------
+
+New features
+''''''''''''
+
+* Executable script to convert Python scripts into Jupyter Notebooks `#148 <https://github.com/sphinx-gallery/sphinx-gallery/pull/148>`_
+
+
+Bug Fixes
+'''''''''
+* Sphinx-Gallery now raises an exception if the matplotlib bakend can
+ not be set to ``'agg'``. This can happen for example if
+ matplotlib.pyplot is imported in conf.py. See `#157
+ <https://github.com/sphinx-gallery/sphinx-gallery/pull/157>`_ for
+ more details.
+* Fix ``backreferences.identify_names`` when module is used without
+ attribute `#173
+ <https://github.com/sphinx-gallery/sphinx-gallery/pull/173>`_. Closes
+ `#172 <https://github.com/sphinx-gallery/sphinx-gallery/issues/172>`_
+ and `#149
+ <https://github.com/sphinx-gallery/sphinx-gallery/issues/149>`_
+* Raise FileNotFoundError when README.txt is not present in the main
+ directory of the examples gallery(`#164
+ <https://github.com/sphinx-gallery/sphinx-gallery/pull/164>`_). Also
+ include extra empty lines after reading README.txt to obtain the
+ correct rendering of the html file.(`#165
+ <https://github.com/sphinx-gallery/sphinx-gallery/pull/165>`_)
+* Ship a License file in PyPI release
+
+v0.1.5
+------
+
+New features
+''''''''''''
+* CSS. Now a tooltip is displayed on the source code blocks to make
+ the doc-resolv functionality more discorverable. Function calls in
+ the source code blocks are hyperlinks to their online documentation.
+* Download buttons have a nicer look across all themes offered by
+ Sphinx
+
+Developer changes
+'''''''''''''''''
+* Support on the fly theme change for local builds of the
+ Sphinx-Gallery docs. Passing to the make target the variable `theme`
+ builds the docs with the new theme. All sphinx themes are available
+ plus read the docs online theme under the value `rtd` as shown in this
+ usage example.::
+
+ $ make html theme=rtd
+
+* Test Sphinx Gallery support on Ubuntu 14 packages, drop Ubuntu 12
+ support. Drop support for Python 2.6 in the conda environment
+
+
+v0.1.4
+------
+
+New features
+''''''''''''
+* Enhanced CSS for download buttons
+* Download buttons at the end of the gallery to download all python
+ scripts or Jupyter notebooks together in a zip file. New config
+ variable `download_all_examples` to toggle this effect. Activated by
+ default
+* Downloadable zip file with all examples as Python scripts and
+ notebooks for each gallery
+* Improved conversion of rst directives to markdown for the Jupyter
+ notebook text blocks
+
+Bug Fixes
+'''''''''
+* When seaborn is imported in a example the plot style preferences are
+ transferred to plots executed afterwards. The CI is set up such that
+ users can follow how to get the compatible versions of
+ mayavi-pandas-seaborn and nomkl in a conda environment to have all
+ the features available.
+* Fix math conversion from example rst to Jupyter notebook text for
+ inline math and multi-line equations
+
+v0.1.3
+------
+
+New features
+''''''''''''
+* Summary of failing examples with traceback at the end of the sphinx
+ build. By default the build exits with a 1 exit code if an example
+ has failed. A list of examples that are expected to fail can be
+ defined in `conf.py` and exit the build with 0
+ exit code. Alternatively it is possible to exit the build as soon as
+ one example has failed.
+* Print aggregated and sorted list of computation times of all examples
+ in the console during the build.
+* For examples that create multiple figures, set the thumbnail image.
+* The ``plot_gallery`` and ``abort_on_example_error`` options can now
+ be specified in ``sphinx_gallery_conf``. The build option (``-D``
+ flag passed to ``sphinx-build``) takes precedence over the
+ ``sphinx_gallery_conf`` option.
+
+Bug Fixes
+'''''''''
+
+* Failing examples are retried on every build
+
+
+v0.1.2
+------
+
+Bug Fixes
+'''''''''
+
+* Examples that use ``if __name__ == '__main__'`` guards are now run
+* Added vertical space between code output and code source in non
+ notebook examples
+
+v0.1.1
+------
+
+Bug Fixes
+'''''''''
+
+* Restore the html-noplot functionality
+* Gallery CSS now implicitly enforces thumbnails width
+
+v0.1.0
+------
+
+Highlights
+''''''''''
+
+Example scripts are now available for download as IPython Notebooks
+`#75 <https://github.com/sphinx-gallery/sphinx-gallery/pull/75>`_
+
+New features
+''''''''''''
+
+* Configurable filename pattern to select which example scripts are
+ executed while building the Gallery
+* Examples script update check are now by md5sum check and not date
+* Broken Examples now display a Broken thumbnail in the gallery view,
+ inside the rendered example traceback is printed. User can also set
+ build process to abort as soon as an example fails.
+* Sorting examples by script size
+* Improve examples style
+
+v0.0.11
+-------
+
+Highlights
+''''''''''
+
+This release incorporates the Notebook styled examples for the gallery
+with PR `#36
+<https://github.com/sphinx-gallery/sphinx-gallery/pull/36>`_
+
+Incompatible Changes
+''''''''''''''''''''
+
+Sphinx-Gallery renames its python module name to sphinx\_gallery this
+follows the discussion raised in `#47
+<https://github.com/sphinx-gallery/sphinx-gallery/issues/47>`_ and
+resolved with `#66
+<https://github.com/sphinx-gallery/sphinx-gallery/pull/66>`_
+
+The gallery configuration dictionary also changes its name to ``sphinx_gallery_conf``
+
+From PR `#36
+<https://github.com/sphinx-gallery/sphinx-gallery/pull/36>`_ it is
+decided into a new namespace convention for images, thumbnails and
+references. See `comment
+<https://github.com/sphinx-gallery/sphinx-gallery/pull/36#issuecomment-121392815>`_
+
+
+v0.0.10
+-------
+
+Highlights
+''''''''''
+
+This release allows to use the Back references. This features
+incorporates fine grained examples galleries listing examples using a
+particular function. `#26
+<https://github.com/sphinx-gallery/sphinx-gallery/pull/26>`_
+
+New features
+''''''''''''
+
+* Shell script to place a local copy of Sphinx-Gallery in your project
+* Support Mayavi plots in the gallery
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..1ad8acd
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,27 @@
+Copyright (c) 2015, Óscar Nájera
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+* Neither the name of sphinx-gallery nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100644
index 0000000..9d3c1c5
--- /dev/null
+++ b/MANIFEST.in
@@ -0,0 +1,2 @@
+include CHANGES.rst
+include LICENSE
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..eb6a177
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,203 @@
+===================================
+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
+
+.. image:: https://readthedocs.org/projects/sphinx-gallery/badge/?version=latest
+ :target: https://sphinx-gallery.readthedocs.io/en/latest/?badge=latest
+ :alt: Documentation Status
+
+.. image:: https://ci.appveyor.com/api/projects/status/github/sphinx-gallery/sphinx-gallery?branch=master&svg=true
+ :target: https://ci.appveyor.com/project/Titan-C/sphinx-gallery/history
+
+
+
+A Sphinx extension that builds an HTML version of any Python
+script and puts it into an examples gallery.
+
+It is extracted from the scikit-learn project and aims to be an
+independent general purpose extension.
+
+Who uses Sphinx-Gallery
+=======================
+
+* `Sphinx-Gallery <https://sphinx-gallery.readthedocs.io/en/latest/auto_examples/index.html>`_
+* `Scikit-learn <http://scikit-learn.org/dev/auto_examples/index.html>`_
+* `Nilearn <https://nilearn.github.io/auto_examples/index.html>`_
+* `MNE-python <https://www.martinos.org/mne/stable/auto_examples/index.html>`_
+* `PyStruct <https://pystruct.github.io/auto_examples/index.html>`_
+* `GIMLi <http://www.pygimli.org/_examples_auto/index.html>`_
+* `Nestle <https://kbarbary.github.io/nestle/examples/index.html>`_
+* `pyRiemann <https://pythonhosted.org/pyriemann/auto_examples/index.html>`_
+* `scikit-image <http://scikit-image.org/docs/dev/auto_examples/>`_
+* `Astropy <http://docs.astropy.org/en/stable/generated/examples/index.html>`_
+* `SunPy <http://docs.sunpy.org/en/stable/generated/gallery/index.html>`_
+* `PySurfer <https://pysurfer.github.io/>`_
+
+Getting the package
+===================
+
+You can do a direct install via pip by using:
+
+.. code-block:: bash
+
+ $ pip install sphinx-gallery
+
+Sphinx-Gallery will not manage its dependencies when installing, thus
+you are required to install them manually. Our minimal dependencies
+are:
+
+* Sphinx
+* Matplotlib
+* Pillow
+
+Sphinx-Gallery has also support for packages like:
+
+* Seaborn
+* Mayavi
+
+Install as developer
+--------------------
+
+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.
+
+You will also need to install the dependencies listed above and `pytest`
+
+To install everything do:
+
+.. code-block:: bash
+
+ $ git clone https://github.com/sphinx-gallery/sphinx-gallery
+ $ cd sphinx-gallery
+ $ pip install -r requirements.txt
+ $ python setup.py develop
+
+In addition, you will need the following dependencies to build the
+documentation:
+
+* Scipy
+* Seaborn
+
+.. _set_up_your_project:
+
+Set up your project
+===================
+
+Let's say your Python project looks like this::
+
+ .
+ ├── doc
+ │ ├── conf.py
+ │ ├── index.rst
+ │ └── Makefile
+ ├── py_module
+ │ ├── __init__.py
+ │ └── mod.py
+ └── examples
+ ├── plot_example.py
+ ├── example.py
+ └── README.txt
+
+Your Python module is on ``py_module``, examples on how to use it are
+in ``examples`` and the ``doc`` folder hold the base documentation
+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::
+
+ extensions = [
+ ...
+ 'sphinx_gallery.gen_gallery',
+ ]
+
+This is to load Sphinx-Gallery as one of your extensions, the ellipsis
+``...`` is to represent your other loaded extensions.
+
+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::
+
+ sphinx_gallery_conf = {
+ # path to your examples scripts
+ 'examples_dirs' : '../examples',
+ # path where to save gallery generated examples
+ 'gallery_dirs' : 'auto_examples'}
+
+The ``gallery_dirs`` is the folder where Sphinx-Gallery will store the
+converted Python scripts into rst files that Sphinx will process into
+HTML.
+
+The structure of the examples folder
+------------------------------------
+
+There are some extra instructions on how to present your examples to Sphinx-Gallery.
+
+* A mandatory ``README.txt`` file with rst syntax to introduce your gallery
+* ``plot_examples.py`` files: Python scripts that have to be executed
+ and output a plot that will be presented in your gallery
+* ``examples.py`` files: Python scripts that will not be executed but will
+ be presented in the gallery
+
+All the Python scripts in the examples folder need to have a docstring. Written
+in rst syntax as it is used in the generated file for the example gallery.
+
+You can have sub-folders in your ``examples`` directory, those will be
+processed by the gallery extension and presented in the gallery, as long as
+they also have a ``README.txt`` file. Sub-folders have to respect the same
+structure examples folder.
+
+If these instructions are not clear enough, this package uses itself, to generated
+its own example gallery. So check the directory structure and the contents of the
+files.
+
+Building the documentation locally
+----------------------------------
+
+In your sphinx documentation directory, ``doc`` execute:
+
+.. code-block:: bash
+
+ $ make html
+
+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:
+
+.. code-block:: bash
+
+ _build/html/auto_examples/index.html
+
+that you can open under your favorite browser.
+
+Once a build is completed all your examples outputs are in cache. Thus
+future rebuilds of your project will not trigger the full execution of
+all your examples saving your a large amount of time on each
+iteration. Only examples which have changed (comparison evaluated by
+md5sum) are built again.
+
+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:
+
+.. code-block:: bash
+
+ clean:
+ rm -rf $(BUILDDIR)/*
+ rm -rf auto_examples/
+
+ html-noplot:
+ $(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @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
diff --git a/appveyor.yml b/appveyor.yml
new file mode 100644
index 0000000..c6b805c
--- /dev/null
+++ b/appveyor.yml
@@ -0,0 +1,45 @@
+
+# CI on Windows via appveyor
+# This file was based on Olivier Grisel's python-appveyor-demo
+
+environment:
+
+ global:
+ PYTHON: "C:\\conda"
+ MINICONDA_VERSION: "latest"
+ CONDA_DEPENDENCIES: "numpy seaborn matplotlib sphinx pillow pytest pytest-cov"
+
+ matrix:
+ - PYTHON_VERSION: "2.7"
+ PYTHON_ARCH: "64"
+ - PYTHON_VERSION: "3.5"
+ PYTHON_ARCH: "64"
+
+platform:
+ -x64
+
+install:
+ - "git clone git://github.com/astropy/ci-helpers.git"
+ - "powershell ci-helpers/appveyor/install-miniconda.ps1"
+ - "SET PATH=%PYTHON%;%PYTHON%\\Scripts;%PATH%"
+ - "activate test"
+ # mayavi only available for Python 2.7 through conda
+ - 'IF "%PYTHON_VERSION%"=="2.7" ( conda install mayavi )'
+
+build: false # Not a C# project, build stuff at the test step instead.
+
+test_script:
+ # Run the project tests
+ - python setup.py test
+ # Build the docs
+ - python setup.py develop
+ - cd doc
+ # The Makefile doesn't work directly on Windows PowerShell because of
+ # slashes (but will work e.g. in Msys-git), so for now do these manually
+ # make html-noplot
+ - sphinx-build -D plot_gallery=0 -b html -d _build\doctrees . _build\html
+ # make html
+ - sphinx-build -b html -d _build\doctrees . _build\html
+
+artifacts:
+ - path: doc\_build\html
diff --git a/bin/copy_sphinxgallery.sh b/bin/copy_sphinxgallery.sh
new file mode 100755
index 0000000..738160d
--- /dev/null
+++ b/bin/copy_sphinxgallery.sh
@@ -0,0 +1,11 @@
+#!/bin/sh
+# Script to do a local install of sphinx-gallery
+rm -rf tmp sphinx_gallery
+
+easy_install -Zeab tmp sphinx-gallery
+
+cp -vru tmp/sphinx-gallery/sphinx_gallery/ .
+
+echo "Remember to add sphinx_gallery to your version control"
+echo "Use in case of git:"
+echo "$ git add sphinx_gallery"
diff --git a/bin/sphx_glr_python_to_jupyter.py b/bin/sphx_glr_python_to_jupyter.py
new file mode 100755
index 0000000..f409b86
--- /dev/null
+++ b/bin/sphx_glr_python_to_jupyter.py
@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+r"""
+Sphinx Gallery Notebook converter
+=================================
+
+Exposes the Sphinx-Gallery Notebook renderer to directly convert Python
+scripts into Jupyter Notebooks.
+
+"""
+# Author: Óscar Nájera
+# License: 3-clause BSD
+
+from __future__ import division, absolute_import, print_function
+
+from sphinx_gallery.notebook import python_to_jupyter_cli
+
+
+if __name__ == '__main__':
+ python_to_jupyter_cli()
diff --git a/circle.yml b/circle.yml
new file mode 100644
index 0000000..e5b6831
--- /dev/null
+++ b/circle.yml
@@ -0,0 +1,45 @@
+machine:
+ environment:
+ # We need to set this variable to let Anaconda take precedence
+ PATH: "/home/ubuntu/miniconda/envs/circleenv/bin:/home/ubuntu/miniconda/bin:$PATH"
+
+dependencies:
+ pre:
+ # Disable pyenv (no cleaner way provided by CircleCI as it prepends pyenv version to PATH)
+ - sudo apt-get install texlive texlive-latex-extra latexmk
+ - rm -rf ~/.pyenv
+ - rm -rf ~/virtualenvs
+ - wget -q https://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O ~/miniconda.sh
+ - chmod +x ~/miniconda.sh
+ - ~/miniconda.sh -b -p /home/ubuntu/miniconda
+ - conda update --yes --quiet conda
+ - conda create -n circleenv --yes pip python=2.7
+ - sed -i "s/ENABLE_USER_SITE = .*/ENABLE_USER_SITE = False/g" /home/ubuntu/miniconda/envs/circleenv/lib/python2.7/site.py
+ - conda install -n circleenv --yes numpy scipy seaborn mayavi setuptools matplotlib pillow sphinx pytest pytest-cov sphinx_rtd_theme
+ - pip install -r requirements.txt
+
+ override:
+ - python setup.py develop
+
+test:
+ override:
+ - python setup.py build_sphinx
+ - SPHX_GLR_THEME=rtd sphinx-build doc rtd_html
+ - SPHX_GLR_THEME=alabaster sphinx-build doc alabaster_html
+ - sphinx-build sphinx_gallery/tests/tinybuild/ tiny_html
+ - cd sphinx_gallery/tests/tinybuild/ && make latexpdf && cp _build/latex/Python.pdf $CIRCLE_ARTIFACTS
+
+general:
+ artifacts:
+ - "doc/_build/html"
+ - "rtd_html"
... 7018 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/sphinx-gallery.git
More information about the Python-modules-commits
mailing list