Skip to content

Commit b7d87d9

Browse files
timhoffmtimhoffm
authored
Merge pull request #9708 from anntzer/confpy
Cleanup doc/conf.py & local sphinx extensions
2 parents a3d1c46 + 734a189 commit b7d87d9

File tree

10 files changed

+200
-201
lines changed

10 files changed

+200
-201
lines changed

‎doc/README.txt

-3
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,3 @@ python documentation system built on top of ReST. This directory contains
3636
* _templates - used by the sphinx build system
3737

3838
* sphinxext - Sphinx extensions for the mpl docs
39-
40-
* mpl_examples - a link to the Matplotlib examples in case any
41-
documentation wants to literal include them

‎doc/conf.py

+21-160
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@
1717
import sphinx
1818
import six
1919
from glob import glob
20-
from sphinx_gallery.sorting import ExplicitOrder
2120

2221
# If your extensions are in another directory, add it here. If the directory
2322
# is relative to the documentation root, use os.path.abspath to make it
@@ -29,14 +28,25 @@
2928

3029
# Add any Sphinx extension module names here, as strings. They can be extensions
3130
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
32-
extensions = ['matplotlib.sphinxext.mathmpl', 'sphinxext.math_symbol_table',
33-
'sphinx.ext.autodoc', 'matplotlib.sphinxext.only_directives',
34-
'sphinx.ext.doctest', 'sphinx.ext.autosummary',
35-
'sphinx.ext.inheritance_diagram', 'sphinx.ext.intersphinx',
36-
'sphinx_gallery.gen_gallery',
37-
'matplotlib.sphinxext.plot_directive',
38-
'sphinxext.github', 'sphinxext.custom_roles',
39-
'numpydoc']
31+
extensions = [
32+
'sphinx.ext.autodoc',
33+
'sphinx.ext.autosummary',
34+
'sphinx.ext.doctest',
35+
'sphinx.ext.inheritance_diagram',
36+
'sphinx.ext.intersphinx',
37+
'IPython.sphinxext.ipython_console_highlighting',
38+
'IPython.sphinxext.ipython_directive',
39+
'numpydoc', # Needs to be loaded *after* autodoc.
40+
'sphinx_gallery.gen_gallery',
41+
'matplotlib.sphinxext.mathmpl',
42+
'matplotlib.sphinxext.only_directives',
43+
'matplotlib.sphinxext.plot_directive',
44+
'sphinxext.custom_roles',
45+
'sphinxext.github',
46+
'sphinxext.math_symbol_table',
47+
'sphinxext.mock_gui_toolkits',
48+
'sphinxext.skip_deprecated',
49+
]
4050

4151
exclude_patterns = ['api/api_changes/*', 'users/whats_new/*']
4252

@@ -61,18 +71,10 @@ def _check_deps():
6171
"The following dependencies are missing to build the "
6272
"documentation: {}".format(", ".join(missing)))
6373

64-
6574
_check_deps()
6675

67-
try:
68-
from unittest.mock import MagicMock
69-
except ImportError:
70-
from mock import MagicMock
71-
72-
73-
# Use IPython's console highlighting by default
74-
extensions.extend(['IPython.sphinxext.ipython_console_highlighting',
75-
'IPython.sphinxext.ipython_directive'])
76+
# Import only after checking for dependencies.
77+
from sphinx_gallery.sorting import ExplicitOrder
7678

7779
if six.PY2:
7880
from distutils.spawn import find_executable
@@ -85,7 +87,6 @@ def _check_deps():
8587
"No binary named dot - you need to install the Graph Visualization "
8688
"software (usually packaged as 'graphviz') to build the documentation")
8789

88-
8990
autosummary_generate = True
9091

9192
autodoc_docstring_signature = True
@@ -334,146 +335,6 @@ def _check_deps():
334335
1),
335336
]
336337

337-
338-
class MyCairo(MagicMock):
339-
version_info = (1, 4, 0)
340-
341-
342-
class MyPyQt4(MagicMock):
343-
class QtGui(object):
344-
# PyQt4.QtGui public classes.
345-
# Generated with
346-
# textwrap.fill([name for name in dir(PyQt4.QtGui)
347-
# if isinstance(getattr(PyQt4.QtGui, name), type)])
348-
_QtGui_public_classes = """\
349-
Display QAbstractButton QAbstractGraphicsShapeItem
350-
QAbstractItemDelegate QAbstractItemView QAbstractPrintDialog
351-
QAbstractProxyModel QAbstractScrollArea QAbstractSlider
352-
QAbstractSpinBox QAbstractTextDocumentLayout QAction QActionEvent
353-
QActionGroup QApplication QBitmap QBoxLayout QBrush QButtonGroup
354-
QCalendarWidget QCheckBox QClipboard QCloseEvent QColor QColorDialog
355-
QColumnView QComboBox QCommandLinkButton QCommonStyle QCompleter
356-
QConicalGradient QContextMenuEvent QCursor QDataWidgetMapper QDateEdit
357-
QDateTimeEdit QDesktopServices QDesktopWidget QDial QDialog
358-
QDialogButtonBox QDirModel QDockWidget QDoubleSpinBox QDoubleValidator
359-
QDrag QDragEnterEvent QDragLeaveEvent QDragMoveEvent QDropEvent
360-
QErrorMessage QFileDialog QFileIconProvider QFileOpenEvent
361-
QFileSystemModel QFocusEvent QFocusFrame QFont QFontComboBox
362-
QFontDatabase QFontDialog QFontInfo QFontMetrics QFontMetricsF
363-
QFormLayout QFrame QGesture QGestureEvent QGestureRecognizer QGlyphRun
364-
QGradient QGraphicsAnchor QGraphicsAnchorLayout QGraphicsBlurEffect
365-
QGraphicsColorizeEffect QGraphicsDropShadowEffect QGraphicsEffect
366-
QGraphicsEllipseItem QGraphicsGridLayout QGraphicsItem
367-
QGraphicsItemAnimation QGraphicsItemGroup QGraphicsLayout
368-
QGraphicsLayoutItem QGraphicsLineItem QGraphicsLinearLayout
369-
QGraphicsObject QGraphicsOpacityEffect QGraphicsPathItem
370-
QGraphicsPixmapItem QGraphicsPolygonItem QGraphicsProxyWidget
371-
QGraphicsRectItem QGraphicsRotation QGraphicsScale QGraphicsScene
372-
QGraphicsSceneContextMenuEvent QGraphicsSceneDragDropEvent
373-
QGraphicsSceneEvent QGraphicsSceneHelpEvent QGraphicsSceneHoverEvent
374-
QGraphicsSceneMouseEvent QGraphicsSceneMoveEvent
375-
QGraphicsSceneResizeEvent QGraphicsSceneWheelEvent
376-
QGraphicsSimpleTextItem QGraphicsTextItem QGraphicsTransform
377-
QGraphicsView QGraphicsWidget QGridLayout QGroupBox QHBoxLayout
378-
QHeaderView QHelpEvent QHideEvent QHoverEvent QIcon QIconDragEvent
379-
QIconEngine QIconEngineV2 QIdentityProxyModel QImage QImageIOHandler
380-
QImageReader QImageWriter QInputContext QInputContextFactory
381-
QInputDialog QInputEvent QInputMethodEvent QIntValidator QItemDelegate
382-
QItemEditorCreatorBase QItemEditorFactory QItemSelection
383-
QItemSelectionModel QItemSelectionRange QKeyEvent QKeyEventTransition
384-
QKeySequence QLCDNumber QLabel QLayout QLayoutItem QLineEdit
385-
QLinearGradient QListView QListWidget QListWidgetItem QMainWindow
386-
QMatrix QMatrix2x2 QMatrix2x3 QMatrix2x4 QMatrix3x2 QMatrix3x3
387-
QMatrix3x4 QMatrix4x2 QMatrix4x3 QMatrix4x4 QMdiArea QMdiSubWindow
388-
QMenu QMenuBar QMessageBox QMimeSource QMouseEvent
389-
QMouseEventTransition QMoveEvent QMovie QPageSetupDialog QPaintDevice
390-
QPaintEngine QPaintEngineState QPaintEvent QPainter QPainterPath
391-
QPainterPathStroker QPalette QPanGesture QPen QPicture QPictureIO
392-
QPinchGesture QPixmap QPixmapCache QPlainTextDocumentLayout
393-
QPlainTextEdit QPolygon QPolygonF QPrintDialog QPrintEngine
394-
QPrintPreviewDialog QPrintPreviewWidget QPrinter QPrinterInfo
395-
QProgressBar QProgressDialog QProxyModel QPushButton QPyTextObject
396-
QQuaternion QRadialGradient QRadioButton QRawFont QRegExpValidator
397-
QRegion QResizeEvent QRubberBand QScrollArea QScrollBar
398-
QSessionManager QShortcut QShortcutEvent QShowEvent QSizeGrip
399-
QSizePolicy QSlider QSortFilterProxyModel QSound QSpacerItem QSpinBox
400-
QSplashScreen QSplitter QSplitterHandle QStackedLayout QStackedWidget
401-
QStandardItem QStandardItemModel QStaticText QStatusBar
402-
QStatusTipEvent QStringListModel QStyle QStyleFactory QStyleHintReturn
403-
QStyleHintReturnMask QStyleHintReturnVariant QStyleOption
404-
QStyleOptionButton QStyleOptionComboBox QStyleOptionComplex
405-
QStyleOptionDockWidget QStyleOptionDockWidgetV2 QStyleOptionFocusRect
406-
QStyleOptionFrame QStyleOptionFrameV2 QStyleOptionFrameV3
407-
QStyleOptionGraphicsItem QStyleOptionGroupBox QStyleOptionHeader
408-
QStyleOptionMenuItem QStyleOptionProgressBar QStyleOptionProgressBarV2
409-
QStyleOptionRubberBand QStyleOptionSizeGrip QStyleOptionSlider
410-
QStyleOptionSpinBox QStyleOptionTab QStyleOptionTabBarBase
411-
QStyleOptionTabBarBaseV2 QStyleOptionTabV2 QStyleOptionTabV3
412-
QStyleOptionTabWidgetFrame QStyleOptionTabWidgetFrameV2
413-
QStyleOptionTitleBar QStyleOptionToolBar QStyleOptionToolBox
414-
QStyleOptionToolBoxV2 QStyleOptionToolButton QStyleOptionViewItem
415-
QStyleOptionViewItemV2 QStyleOptionViewItemV3 QStyleOptionViewItemV4
416-
QStylePainter QStyledItemDelegate QSwipeGesture QSyntaxHighlighter
417-
QSystemTrayIcon QTabBar QTabWidget QTableView QTableWidget
418-
QTableWidgetItem QTableWidgetSelectionRange QTabletEvent
419-
QTapAndHoldGesture QTapGesture QTextBlock QTextBlockFormat
420-
QTextBlockGroup QTextBlockUserData QTextBrowser QTextCharFormat
421-
QTextCursor QTextDocument QTextDocumentFragment QTextDocumentWriter
422-
QTextEdit QTextFormat QTextFragment QTextFrame QTextFrameFormat
423-
QTextImageFormat QTextInlineObject QTextItem QTextLayout QTextLength
424-
QTextLine QTextList QTextListFormat QTextObject QTextObjectInterface
425-
QTextOption QTextTable QTextTableCell QTextTableCellFormat
426-
QTextTableFormat QTimeEdit QToolBar QToolBox QToolButton QToolTip
427-
QTouchEvent QTransform QTreeView QTreeWidget QTreeWidgetItem
428-
QTreeWidgetItemIterator QUndoCommand QUndoGroup QUndoStack QUndoView
429-
QVBoxLayout QValidator QVector2D QVector3D QVector4D QWhatsThis
430-
QWhatsThisClickedEvent QWheelEvent QWidget QWidgetAction QWidgetItem
431-
QWindowStateChangeEvent QWizard QWizardPage QWorkspace
432-
QX11EmbedContainer QX11EmbedWidget QX11Info
433-
"""
434-
for _name in _QtGui_public_classes.split():
435-
locals()[_name] = type(_name, (), {})
436-
del _name
437-
438-
439-
class MySip(MagicMock):
440-
def getapi(*args):
441-
return 1
442-
443-
444-
class MyWX(MagicMock):
445-
class Panel(object):
446-
pass
447-
448-
class ToolBar(object):
449-
pass
450-
451-
class Frame(object):
452-
pass
453-
454-
VERSION_STRING = '2.9'
455-
456-
457-
sys.modules['cairo'] = MyCairo()
458-
sys.modules['cairo'].__name__ = 'cairocffi'
459-
sys.modules['PyQt4'] = MyPyQt4()
460-
sys.modules['sip'] = MySip()
461-
sys.modules['wx'] = MyWX()
462-
sys.modules['wxversion'] = MagicMock()
463-
464338
# numpydoc config
465339

466340
numpydoc_show_class_members = False
467-
468-
# Skip deprecated members
469-
470-
def skip_deprecated(app, what, name, obj, skip, options):
471-
if skip:
472-
return skip
473-
skipped = {"matplotlib.colors": ["ColorConverter", "hex2color", "rgb2hex"]}
474-
skip_list = skipped.get(getattr(obj, "__module__", None))
475-
if skip_list is not None:
476-
return getattr(obj, "__name__", None) in skip_list
477-
478-
def setup(app):
479-
app.connect('autodoc-skip-member', skip_deprecated)

‎doc/devel/documenting_mpl.rst

+9-16
Original file line numberDiff line numberDiff line change
@@ -276,27 +276,20 @@ tutorial in :doc:`/tutorials/introductory/customizing`::
276276

277277
.. literalinclude:: ../../_static/matplotlibrc
278278

279-
This is rendered as :doc:`/tutorials/introductory/customizing` (see the
280-
bottom of the page. Note that this is in a tutorial; See
281-
:ref:`writing-examples-and-tutorials` below)
279+
This is rendered at the bottom of :doc:`/tutorials/introductory/customizing`.
280+
Note that this is in a tutorial; see :ref:`writing-examples-and-tutorials`
281+
below.
282282

283-
In the top level :file:`doc` directory there are symlinks pointing to the
284-
Matplotlib :file:`examples`:
285-
286-
.. code-block:: sh
287-
288-
home:~/mpl/doc> ls -l mpl_*
289-
mpl_examples -> ../examples
290-
291-
Plots are included from the examples dir using the symlink:
283+
The examples directory is also copied to :file:`doc/gallery` by sphinx-gallery,
284+
so plots from the examples directory can be included using
292285

293286
.. code-block:: rst
294287
295-
.. plot:: mpl_examples/pylab_examples/simple_plot.py
288+
.. plot:: gallery/pylab_examples/simple_plot.py
296289
297-
Note that the python script that generates the plot is referred to, rather
298-
than any plot that is created. `Sphinx Gallery`_ will provide the incorrect
299-
reference when the documentation is built.
290+
Note that the python script that generates the plot is referred to, rather than
291+
any plot that is created. Sphinx-gallery will provide the correct reference
292+
when the documentation is built.
300293

301294

302295
.. _writing-docstrings:

‎doc/mpl_examples

-1
This file was deleted.

‎doc/sphinxext/math_symbol_table.py

+16-18
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,34 @@
11
from __future__ import print_function
22
symbols = [
33
["Lower-case Greek",
4-
5,
4+
6,
55
r"""\alpha \beta \gamma \chi \delta \epsilon \eta \iota \kappa
66
\lambda \mu \nu \omega \phi \pi \psi \rho \sigma \tau \theta
77
\upsilon \xi \zeta \digamma \varepsilon \varkappa \varphi
88
\varpi \varrho \varsigma \vartheta"""],
99
["Upper-case Greek",
10-
6,
10+
8,
1111
r"""\Delta \Gamma \Lambda \Omega \Phi \Pi \Psi \Sigma \Theta
1212
\Upsilon \Xi \mho \nabla"""],
1313
["Hebrew",
14-
4,
14+
6,
1515
r"""\aleph \beth \daleth \gimel"""],
1616
["Delimiters",
1717
6,
1818
r"""| \{ \lfloor / \Uparrow \llcorner \vert \} \rfloor \backslash
1919
\uparrow \lrcorner \| \langle \lceil [ \Downarrow \ulcorner
2020
\Vert \rangle \rceil ] \downarrow \urcorner"""],
2121
["Big symbols",
22-
5,
22+
6,
2323
r"""\bigcap \bigcup \bigodot \bigoplus \bigotimes \biguplus
2424
\bigvee \bigwedge \coprod \oint \prod \sum \int"""],
2525
["Standard function names",
26-
4,
26+
6,
2727
r"""\arccos \csc \ker \min \arcsin \deg \lg \Pr \arctan \det \lim
2828
\gcd \ln \sup \cot \hom \log \tan \coth \inf \max \tanh
2929
\sec \arg \dim \liminf \sin \cos \exp \limsup \sinh \cosh"""],
3030
["Binary operation and relation symbols",
31-
3,
31+
4,
3232
r"""\ast \pm \slash \cap \star \mp \cup \cdot \uplus
3333
\triangleleft \circ \odot \sqcap \triangleright \bullet \ominus
3434
\sqcup \bigcirc \oplus \wedge \diamond \oslash \vee
@@ -60,7 +60,7 @@
6060
\Doteq \nsubset \eqcolon \ne
6161
"""],
6262
["Arrow symbols",
63-
2,
63+
4,
6464
r"""\leftarrow \longleftarrow \uparrow \Leftarrow \Longleftarrow
6565
\Uparrow \rightarrow \longrightarrow \downarrow \Rightarrow
6666
\Longrightarrow \Downarrow \leftrightarrow \updownarrow
@@ -83,7 +83,7 @@
8383
\leftsquigarrow
8484
"""],
8585
["Miscellaneous symbols",
86-
3,
86+
4,
8787
r"""\neg \infty \forall \wp \exists \bigstar \angle \partial
8888
\nexists \measuredangle \eth \emptyset \sphericalangle \clubsuit
8989
\varnothing \complement \diamondsuit \imath \Finv \triangledown
@@ -111,16 +111,14 @@ def get_n(n, l):
111111
lines.append('')
112112
max_width = max(map(len, syms)) * 2 + 16
113113
header = " " + (('=' * max_width) + ' ') * columns
114-
format = '%%%ds' % max_width
115-
for chunk in get_n(20, get_n(columns, syms)):
116-
lines.append(header)
117-
for part in chunk:
118-
line = []
119-
for sym in part:
120-
line.append(format % (":math:`%s` ``%s``" % (sym, sym)))
121-
lines.append(" " + " ".join(line))
122-
lines.append(header)
123-
lines.append('')
114+
lines.append(header)
115+
for part in get_n(columns, syms):
116+
line = " " + " ".join(
117+
":math:`{0}` ``{0}``".format(sym).rjust(max_width)
118+
for sym in part)
119+
lines.append(line)
120+
lines.append(header)
121+
lines.append('')
124122

125123
state_machine.insert_input(lines, "Symbol table")
126124
return []

0 commit comments

Comments
 (0)