/usr/lib/python2.7/dist-packages/sphinx_gallery-0.1.13.egg-info/PKG-INFO is in python-sphinx-gallery 0.1.13-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 | Metadata-Version: 1.1
Name: sphinx-gallery
Version: 0.1.13
Summary: Sphinx extension to automatically generate an examples gallery
Home-page: https://github.com/sphinx-gallery/sphinx-gallery
Author: Óscar Nájera
Author-email: najera.oscar@gmail.com
License: 3-clause BSD
Description-Content-Type: UNKNOWN
Description: ===================================
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
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Sphinx :: Extension
Classifier: Programming Language :: Python
|