Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Sphinx gallery #902

Closed
wants to merge 6 commits into from
Closed

Sphinx gallery #902

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
fb52ad0
sphinx gallery init
choldgraf Jun 25, 2017
9617fc8
updating paths and SG files
choldgraf Jun 26, 2017
74e241f
adding auto-linking
choldgraf Jun 29, 2017
0c98fa6
updating sphinx gallery builds
choldgraf Jul 6, 2017
2f5b9de
adding CSS to remote init.py files
choldgraf Jul 6, 2017
b4d77ac
Merge branch 'master' into sphinx_gallery
choldgraf Aug 10, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
6 changes: 6 additions & 0 deletions .gitignore
View file
Open in desktop
Expand Up @@ -21,6 +21,8 @@ lib/cartopy/tests/mpl/output/
docs/source/cartopy_outline.rst
docs/source/examples
docs/source/gallery.rst
docs/source/gallery
docs/source/api
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this api section is auto-generated by sphinx-gallery and can be used to build mini-galleries for specific functions / classes if desired


# some data files:
lib/cartopy/data/SRTM3
Expand All @@ -40,9 +42,13 @@ lib/cartopy/siteconfig.py
\#*
\.\#*
*.swp
.ipynb_checkpoints/

# Operating system files
\.DS_Store
.cache/
__pycache__/

# Egg that gets created with 'pip install -v -e .'
lib/Cartopy.egg-info/
.eggs/
1 change: 1 addition & 0 deletions docs/Makefile
View file
Open in desktop
Expand Up @@ -45,6 +45,7 @@ clean:

html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
python add_noshow.py
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

Expand Down
20 changes: 20 additions & 0 deletions docs/add_noshow.py
View file
Open in desktop
@@ -0,0 +1,20 @@
from bs4 import BeautifulSoup as bs

path_html = 'build/html/gallery/index.html'
with open(path_html, 'r') as ff:
html = bs(ff.read(), "lxml")

# Search for thumbnails that link to __init__ files
thumbs = html.find_all('div', attrs={'class': 'sphx-glr-thumbcontainer'})
for div in thumbs:
links = div.find_all('a')

# If you find any, add a class that will make it invisible
any_init = any('__init__' in ilink.attrs['href'] for ilink in links)
if any_init:
div.attrs['class'] += ['dontshow']

# Now update the HTML
with open(path_html, 'w') as ff:
out_html = html.prettify(html.original_encoding)
ff.write(out_html)
6 changes: 6 additions & 0 deletions docs/doc-requirements.txt
View file
Open in desktop
@@ -0,0 +1,6 @@
netCDF4
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I included an extra .txt file because getting the docs to build required several extra requirements I didn't have. I can either clean this up / add to it if folks have suggestions, or remove it if people prefer not to have it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't there be sphinx and sphinx-gallery in here at least?

iris
cf_units
sphinx
sphinx-gallery
beautifulsoup4
16 changes: 16 additions & 0 deletions docs/source/_static/layout.css
View file
Open in desktop
Expand Up @@ -18,3 +18,19 @@ h1 {
padding: 20px 0px 20px 75px;
margin: 15px 0 10px 0;
}

/* Sphinx Gallery */

div#cartopy-gallery.section {
overflow: hidden;
}

div.section div.figure {
padding-left: 0 !important;
text-align: center;
}

/* hack to make the __init__.py files not display in SG*/
div.dontshow {
display: none !important;
}
35 changes: 35 additions & 0 deletions docs/source/_templates/automodule.rst
View file
Open in desktop
@@ -0,0 +1,35 @@
{{ fullname | escape | underline}}


.. automodule:: {{ fullname }}
:no-members:
:no-inherited-members:

{% block classes %}
{% if classes %}

Classes
-------

.. autosummary::
:template: autosummary.rst
:toctree:
{% for item in classes %}{% if item not in ['zip', 'map', 'reduce'] %}
{{ item }}{% endif %}{% endfor %}
{% endif %}
{% endblock %}

{% block functions %}
{% if functions %}

Functions
---------

.. autosummary::
:template: autosummary.rst
:toctree:

{% for item in functions %}{% if item not in ['zip', 'map', 'reduce'] %}
{{ item }}{% endif %}{% endfor %}
{% endif %}
{% endblock %}
16 changes: 16 additions & 0 deletions docs/source/_templates/autosummary.rst
View file
Open in desktop
@@ -0,0 +1,16 @@
{{ fullname | escape | underline}}


.. currentmodule:: {{ module }}

.. auto{{ objtype }}:: {{ objname }}

{% if objtype in ['class', 'method', 'function'] %}

.. include:: {{module}}.{{objname}}.examples

.. raw:: html

<div class="clearer"></div>

{% endif %}
6 changes: 3 additions & 3 deletions docs/source/_templates/layout.html
View file
Open in desktop
Expand Up @@ -12,8 +12,8 @@

{% block rootrellink %}
<li><a href="{{ pathto('index') }}">home</a>|&nbsp;</li>
<li><a href="{{ pathto('gallery') }}">gallery</a>|&nbsp;</li>
<li><a href="{{ pathto('gallery/index') }}">gallery</a>|&nbsp;</li>

{% endblock %}


Expand All @@ -28,7 +28,7 @@

{% block sidebarlogo %}
<a href="{{ pathto('index') }}">
<img src="{{pathto("_static/cartopy.png", 1) }}"
<img src="{{pathto("_static/cartopy.png", 1) }}"
border="0" alt="Cartopy" style="margin-left: -60px;"/>
</a>

Expand Down
37 changes: 22 additions & 15 deletions docs/source/conf.py
View file
Open in desktop
@@ -1,4 +1,4 @@
# (C) British Crown Copyright 2011 - 2016, Met Office
# (C) British Crown Copyright 2011 - 2017, Met Office
#
# This file is part of cartopy.
#
Expand Down Expand Up @@ -45,19 +45,20 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'cartopy.sphinxext.summarise_package',
'cartopy.sphinxext.gallery',
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'sphinx.ext.extlinks',
'sphinx.ext.autosummary',
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would you mind removing this from the PR? My prior experience suggests that in certain situations having autogenerated docs is worse than having no docs at all - cartopy is no shining start wrt its docs, but what is documented is generally more readable than most autogenerated API summary (e.g. http://scitools.org.uk/iris/docs/latest/iris/iris.html. To be clear - I implemented that autosummary generation for iris, so I'm explicitly not bad-mouthing anybody else 😉 ). I'm expecting to be able to invest some significant effort on cartopy's manually crafted docs over the coming months, and so keeping the autosummary would mask the shortcomings.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the main reason for autosummary is that it lets you auto-generate mini-galleries for functions etc with sphinx-gallery. In conjunction with the template files in this PR, that will generate pages like this matplotlib example. Usually I don't use automodule either, but instead do it class-by-class (or function-by-function) to get the most modularity over my docs

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pelson what's the decision on this? Do you want the autosummary removed or not? IMO it should be removed; I'm not convinced enough by @choldgraf's justification for keeping it in.

#'sphinxcontrib.napoleon', (Needs work before this can be enabled.)
# 'matplotlib.sphinxext.plot_directive'
# We use a local copy of the plot_directive until
# https://github.com/matplotlib/matplotlib/pull/6213 is available in order
# to benefit from cached rebuilds of plots.
'sphinxext.plot_directive'
'sphinxext.plot_directive',
'sphinx_gallery.gen_gallery',
]

import matplotlib
Expand Down Expand Up @@ -89,6 +90,20 @@
# The full version, including alpha/beta/rc tags.
release = cartopy.__version__

# Sphinx gallery configuration
sphinx_gallery_conf = {
'examples_dirs': ['../../lib/cartopy/examples'],
'filename_pattern': '^((?!sgskip).)*$',
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any file that includes sgskip in its title will not be run by sphinx-gallery. Right now this is only the geostationary example because it kept hanging on my computer and I couldn't debug it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It just takes a long time to reproject things, about 2 minutes for me.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah I see - I wonder if this is just because I'm working on a relatively underpowered laptop...I'll remove the sgskip and will add some print statements so it doesn't look like it's hanging

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So we can now remove this line, right?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this line should stay in case you ever want to have an example that isn't run by sphinx-gallery...it's a configuration option so won't change the behavior of the docs unless "sgskip" is in a file name

'gallery_dirs': ['gallery'],
'doc_module': ('cartopy',),
'reference_url': {'matplotlib': 'http://matplotlib.org',
'numpy': 'http://docs.scipy.org/doc/numpy/reference',
'scipy': 'http://docs.scipy.org/doc/scipy/reference',
'shapely': 'http://toblerity.org/shapely',
'cartopy': None},
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These two lines should be removable at this point?

(the second line is the backreferences_dir one)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you want to remove the backreferences_dir line? I'm not sure which you're referring to

'backreferences_dir': 'api/_as_gen', # Not currently used but kept for future
}

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
Expand Down Expand Up @@ -324,8 +339,8 @@

# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
'matplotlib': ('http://matplotlib.org', None),
'shapely': ('http://toblerity.org/shapely', None),}
'matplotlib': ('https://matplotlib.org', None),
'shapely': ('https://toblerity.org/shapely', None),}



Expand All @@ -347,14 +362,6 @@
summarise_package_fnames = ['cartopy_outline.rst']


############ gallery/examples extension ###########

#gallery_allowed_tags = None
#gallery_tag_order = None
gallery_name = 'gallery.rst'
examples_package_name = 'cartopy.examples'


############ plot directive ##############

plot_html_show_formats = False
Expand All @@ -363,10 +370,10 @@
'figure.subplot.top': 0.96,
'figure.subplot.left': 0.04,
'figure.subplot.right': 0.96}
plot_formats = (('thumb.png', 20),
plot_formats = [('thumb.png', 20),
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This kept giving me a warning when building the site saying it should be a list, so I updated it

'png',
'pdf'
)
]


############ autodoc config ##############
Expand Down
14 changes: 7 additions & 7 deletions docs/source/index.rst
View file
Open in desktop
Expand Up @@ -19,12 +19,13 @@ Some of the key features of cartopy are:
* object oriented projection definitions
* point, line, vector, polygon and image transformations between projections
* integration to expose advanced mapping in matplotlib with a simple and intuitive interface
* powerful vector data handling by integrating shapefile reading with Shapely capabilities
* powerful vector data handling by integrating shapefile reading with Shapely capabilities

Cartopy is licensed under `GNU Lesser General Public License <https://www.gnu.org/licenses/lgpl.html>`_
and is at version |version|. You can find the source code for cartopy on
`our github page <https://github.com/SciTools/cartopy>`_.

.. _getting-started:

Getting started
===============
Expand Down Expand Up @@ -66,23 +67,23 @@ outlines recent changes, new features, and future development plans.
Getting involved
================

Cartopy was originally developed at the UK Met Office to allow scientists to visualise
their data on maps quickly, easily and most importantly, accurately.
Cartopy was originally developed at the UK Met Office to allow scientists to visualise
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe all of these are just trailing whitespace updates that my editor apparently auto-corrected. LMK if you want me to revert these for some reason

their data on maps quickly, easily and most importantly, accurately.
Cartopy has been made freely available under the terms of the
`GNU Lesser General Public License <https://www.gnu.org/licenses/lgpl.html>`_. It is suitable to be used in a variety
of scientific fields and has an :doc:`active development community <contributors>`.

There are many ways to get involved in the development of cartopy:

* If you write a paper which makes use of cartopy, please consider :doc:`citing <citation>` it.
* If you publish the maps and plots, please consider the required :ref:`attribution of copyright <referencing_copyright>` for the data.
* If you publish the maps and plots, please consider the required :ref:`attribution of copyright <referencing_copyright>` for the data.
* Report bugs to https://github.com/SciTools/cartopy/issues (please look to see if there are any outstanding
bugs which cover the issue before making a new one).
* Help others with support questions on `stackoverflow <https://stackoverflow.com/questions/tagged/cartopy>`_.
* Contribute to the documentation fixing typos, adding examples, explaining things more clearly, or even
re-designing its layout/logos etc..
* Contribute bug fixes (:issues:`a list of outstanding bugs can be found on github <bug>`).
* Contribute enhancements and new features
* Contribute enhancements and new features
(:issues:`a wish list of features can also be found on github <wishlist>`).

Development discussion takes place on the `matplotlib-devel mailing list
Expand All @@ -95,8 +96,7 @@ subjects prefixed with "cartopy: ".
:glob:
:hidden:

gallery
examples/*
gallery/*
citation
copyright
contributors
24 changes: 13 additions & 11 deletions docs/source/matplotlib/advanced_plotting.rst
View file
Open in desktop
Expand Up @@ -4,10 +4,10 @@ More advanced mapping with cartopy and matplotlib
From the outset, cartopy's purpose has been to simplify and improve the quality of
mapping visualisations available for scientific data. Thanks to the simplicity of the cartopy
interface, in many cases the hardest part of producing such visualisations is getting
hold of the data in the first place. To address this, a Python package,
`Iris <http://scitools.org.uk/iris/>`_, has been created to make loading and saving data from a
variety of gridded datasets easier. Some of the following examples make use of the Iris
loading capabilities, while others use the netCDF4 Python package so as to show a range
hold of the data in the first place. To address this, a Python package,
`Iris <http://scitools.org.uk/iris/>`_, has been created to make loading and saving data from a
variety of gridded datasets easier. Some of the following examples make use of the Iris
loading capabilities, while others use the netCDF4 Python package so as to show a range
of different approaches to data loading.


Expand Down Expand Up @@ -139,16 +139,18 @@ visualising vector fields:
:meth:`streamplots <cartopy.mpl.geoaxes.GeoAxes.streamplot>` (:ref:`example <examples-streamplot>`)
each with their own benefits for displaying certain vector field forms.

.. literalinclude:: /examples/arrows.py
.. plot:: examples/arrows.py
.. figure:: ../gallery/vector_data/images/sphx_glr_arrows_001.png
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are updated so that old figures generated with the plot directive are now linking to the sphinx-gallery image (the end result is basically the same)

:target: ../gallery/vector_data/arrows.html
:align: center
:scale: 50
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems too small.


Since both :meth:`~cartopy.mpl.geoaxes.GeoAxes.quiver` and :meth:`~cartopy.mpl.geoaxes.GeoAxes.barbs`
are visualisations which draw every vector supplied, there is an additional option to "regrid" the
vector field into a regular grid on the target projection (done via
:func:`cartopy.vector_transform.vector_scalar_to_grid`). This is enabled with the ``regrid_shape``
keyword and can have a massive impact on the effectiveness of the visualisation:
keyword and can have a massive impact on the effectiveness of the visualisation:


.. literalinclude:: /examples/regridding_arrows.py

.. plot:: examples/regridding_arrows.py
.. figure:: ../gallery/vector_data/images/sphx_glr_regridding_arrows_001.png
:target: ../gallery/vector_data/regridding_arrows.html
:align: center
:scale: 50
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also a bit small.

20 changes: 10 additions & 10 deletions docs/source/matplotlib/feature_interface.rst
View file
Open in desktop
Expand Up @@ -3,7 +3,7 @@
The cartopy Feature interface
=============================

The :ref:`data copyright, license and attribution <referencing_copyright>` can be blended on the map using `text annotations (mpl docs) <http://matplotlib.org/users/annotations_intro.html>`_ as shown in `feature_creation <../examples/feature_creation.html>`_.
The :ref:`data copyright, license and attribution <referencing_copyright>` can be blended on the map using `text annotations (mpl docs) <http://matplotlib.org/users/annotations_intro.html>`_ as shown in `feature_creation <../gallery/lines_and_polygons/feature_creation.html>`_.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It isn't ideal to change the URL of the examples (because of StackOverflow/Google links etc.). Any way of avoiding it?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmmm, not without changing the directory structure of the examples. In other projects where we've implemented sphinx gallery we just kinda took a "rip the band-aid off" approach...I agree that's unfortunate :-/


.. currentmodule:: cartopy.feature

Expand All @@ -19,15 +19,15 @@ Natural Earth or GSHHS shapefiles.


.. autoclass:: ShapelyFeature

.. autoclass:: NaturalEarthFeature

.. autoclass:: GSHHSFeature

----------

To simplify some very common cases, some pre-defined Features exist as :mod:`cartopy.feature`
constants. The pre-defined Features are all small-scale (1:110m)
constants. The pre-defined Features are all small-scale (1:110m)
`Natural Earth <http://www.naturalearthdata.com>`_ datasets, and can be added with methods
such as :func:`GeoAxes.add_feature <cartopy.mpl.geoaxes.GeoAxes.add_feature>`:

Expand All @@ -47,7 +47,7 @@ Name Description
Any Natural Earth dataset can easily be used by creating an
instance of :class:`cartopy.feature.NaturalEarthFeature`. For
example::

import cartopy.feature as cfeature
land_50m = cfeature.NaturalEarthFeature('physical', 'land', '50m',
edgecolor='face',
Expand All @@ -63,15 +63,15 @@ For a full list of names in this dictionary:
>>> import cartopy.feature
>>> sorted(cartopy.feature.COLORS.keys())
['land', 'land_alt1', 'water']


------------


Example of using the Feature class with the matplotlib interface
----------------------------------------------------------------

.. literalinclude:: /examples/feature_creation.py
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I definitely think we need to have a separation between what should live in the gallery, and what is useful as inline examples within the context of a chapter.

Cartopy hasn't got this completely right though - for example, there are a number of inline examples that really should be in the gallery: http://scitools.org.uk/cartopy/docs/v0.15/matplotlib/advanced_plotting.html#block-plots

Could we do the promotion of inline/contextual examples -> gallery examples as a separate PR?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I could also include the literalinclude in there as well if that's preferred, but if you don't want that in this PR I can take them out.


.. plot:: examples/feature_creation.py

.. figure:: ../gallery/lines_and_polygons/images/sphx_glr_feature_creation_001.png
:target: ../gallery/lines_and_polygons/feature_creation.html
:align: center
:scale: 50
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also small.