Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

MEP10: adding numpydoc and activating autosummary #1665

Merged
merged 5 commits into from

3 participants

@NelleV
Collaborator

Here is the first step in implementing MEP10 (point 1, and part of point 3)

  • Added numpydoc to the sphinx extension
  • Added sphinx's autosummary
  • Made the output a little prettier (I hope).

Here is the screenshot of a page of the API
MEP10_after

I chose to ship numpydoc with matplotlib, instead of asking developpers to install it. That point is debatable.
Also, because of numpydoc, the documentation will not build for sphinx below 1.0.

@pelson
Collaborator

I chose to ship numpydoc with matplotlib, instead of asking developpers to install it. That point is debatable.

Agreed - I don't think it should be in there personally - it is a reasonable dependency (and since it is a python package is easy enough to install). My only hesitation is in making sure that the error, when a developer doesn't have numpydoc, is a good and clear one.

Nice change @NelleV

@mdboom
Owner

Thanks for taking this on. This is really going to improve things.

I'm of two minds about including numpydoc. One thing to consider is that once #1454 is merged, we can use setuptools to automatically install it for us. But I'm also happy to leave it in and remove it later (should be easy enough to do) if there's enough desire to do so.

@NelleV
Collaborator

Should we merge it as is, and see whether we want to keep numpydoc? Despite this PR being very preliminary work, I think it would already be a great addition to the docs.

@pelson
Collaborator

Should we merge it as is, and see whether we want to keep numpydoc?

I feelings on this are to go the other way around. Lets depend on numpydoc rather than ship it and subsequently update docstrings sequentially and systematically in distinct pull requests.

There is no compelling reason to ship numpydoc with mpl, and therefore adding the dependency as part of the codebase adds the possibility, in the future, of diverging versions (in precisely the same way that the plot directive did).

@NelleV
Collaborator

I've deleted numpydoc from the source code, and I've updated the documentation to mention the dependency on numpydoc. I've also added a check that numpydoc is installed in sphinx's setup file, and raised an import error with a more explicit message on the fact we need it.

@pelson
Collaborator

Excellent. @mdboom - please merge when your happy. :+1:

@mdboom
Owner

Looks good. When #1454 is merged (there's still some puzzling issues with it on Travis), we can make the dependency on numpydoc explicit and pip should install it for us. Until then, I think it's fine to expect developers to have it installed already.

Merging. Thanks for all this work.

@mdboom mdboom merged commit 39a54e2 into matplotlib:master
@pelson pelson commented on the diff
doc/conf.py
((6 lines not shown))
'matplotlib.sphinxext.plot_directive', 'sphinx.ext.inheritance_diagram',
'gen_gallery', 'gen_rst',
- 'matplotlib.sphinxext.ipython_console_highlighting', 'github']
+ 'matplotlib.sphinxext.ipython_console_highlighting', 'github',
+ 'numpy_ext.numpydoc']
@pelson Collaborator
pelson added a note

This should be numpydoc. I've submitted a PR to fix this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@pelson
Collaborator

@NelleV - I'm not getting the nice odd-even colour scheme with the method table - I the classes of my table rows are row-odd and row-even. Is this a numpydoc version issue do you think? I've got numpydoc 0.4 from pypi (which doesn't have a numpydoc.__version__ attribute).

@pelson
Collaborator

I'm also getting two method tables for Figure, but only one for AxesStack (in build/html/api/figure_api.html?highlight=figure#matplotlib.figure.AxesStack).

Any tips?

@NelleV
Collaborator

@pelson I'm not sure.. What version of sphinx are you using?
It works well on my computer. I also have numpydoc 0.4

@pelson
Collaborator

Sphinx 1.1.3.

@NelleV
Collaborator

@pelson Same here. Have you made a "python make.py clean" before rebuilding the documentation ?

@NelleV NelleV deleted the NelleV:MEP10 branch
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Jan 16, 2013
  1. @NelleV
  2. @NelleV
  3. @NelleV

    ENH Made the docutils tables generated with the numpydoc in the docum…

    NelleV authored
    …entation a little prettier
Commits on Jan 21, 2013
  1. @NelleV

    Removed numpydoc

    NelleV authored
  2. @NelleV
This page is out of date. Refresh to see the latest.
Showing with 56 additions and 8 deletions.
  1. +30 −0 doc/_static/mpl.css
  2. +23 −5 doc/conf.py
  3. +3 −3 doc/devel/documenting_mpl.rst
View
30 doc/_static/mpl.css
@@ -505,3 +505,33 @@ ul.search li div.context {
ul.keywordmatches li.goodmatch a {
font-weight: bold;
}
+
+table.docutils {
+ border-spacing: 2px;
+ border: collapse;
+ border-top-width: 1px;
+ border-right-width: 0px;
+ border-bottom-width: 1px;
+ border-left-width: 0px;
+}
+
+table.docutils tr:nth-child(even) {
+ background-color: #F3F3FF;
+}
+table.docutils tr:nth-child(odd) {
+ background-color: #FFFFEE;
+}
+
+table.docutils tr {
+ border-style: solid none solid none;
+ border-width: 1px 0 1px 0;
+ border-color: #AAAAAA;
+}
+
+table.docutils th {
+ padding: 1px 8px 1px 5px;
+}
+
+table.docutils td {
+ border-width: 1px 0 1px 0;
+}
View
28 doc/conf.py
@@ -11,12 +11,14 @@
# All configuration values have a default value; values that are commented out
# serve to show the default value.
-import sys, os
+import os
+import sys
+import sphinx
# If your extensions are in another directory, add it here. If the directory
# is relative to the documentation root, use os.path.abspath to make it
# absolute, like shown here.
-sys.path.append(os.path.abspath('sphinxext'))
+sys.path.insert(0, os.path.abspath('sphinxext'))
# General configuration
# ---------------------
@@ -25,10 +27,24 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['matplotlib.sphinxext.mathmpl', 'math_symbol_table',
'sphinx.ext.autodoc', 'matplotlib.sphinxext.only_directives',
- 'sphinx.ext.doctest',
+ 'sphinx.ext.doctest', 'sphinx.ext.autosummary',
'matplotlib.sphinxext.plot_directive', 'sphinx.ext.inheritance_diagram',
'gen_gallery', 'gen_rst',
- 'matplotlib.sphinxext.ipython_console_highlighting', 'github']
+ 'matplotlib.sphinxext.ipython_console_highlighting', 'github',
+ 'numpy_ext.numpydoc']
@pelson Collaborator
pelson added a note

This should be numpydoc. I've submitted a PR to fix this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+
+try:
+ import numpydoc
+except ImportError:
+ raise ImportError("No modyle named numpydoc - you need to install "
+ "numpydoc to build the documentation.")
+
+
+autosummary_generate = True
+
+if sphinx.__version__ >= 1.1:
+ autodoc_docstring_signature = True
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -133,7 +149,9 @@
# Additional templates that should be rendered to pages, maps page names to
# template names.
-html_additional_pages = {'index': 'index.html', 'gallery':'gallery.html', 'citing':'citing.html'}
+html_additional_pages = {'index': 'index.html',
+ 'gallery':'gallery.html',
+ 'citing': 'citing.html'}
# If false, no module index is generated.
#html_use_modindex = True
View
6 doc/devel/documenting_mpl.rst
@@ -7,9 +7,9 @@ Documenting matplotlib
Getting started
===============
-The documentation for matplotlib is generated from ReStructured Text
-using the Sphinx_ documentation generation tool. Sphinx-1.0 or later
-is required.
+The documentation for matplotlib is generated from ReStructured Text using the
+Sphinx_ documentation generation tool. Sphinx-1.0 or later and numpydoc 0.4 or
+later is required.
The documentation sources are found in the :file:`doc/` directory in
the trunk. To build the users guide in html format, cd into
Something went wrong with that request. Please try again.