Skip to content

Cleanup doc/conf.py & local sphinx extensions #9708

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

Merged
merged 2 commits into from
Feb 6, 2018
Merged

Cleanup doc/conf.py & local sphinx extensions #9708

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
de81397
Cleanup doc/conf.py.
anntzer Nov 6, 2017
734a189
Get rid of the mpl_examples symlink.
anntzer Jan 20, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions doc/README.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,3 @@ python documentation system built on top of ReST. This directory contains
* _templates - used by the sphinx build system

* sphinxext - Sphinx extensions for the mpl docs

* mpl_examples - a link to the Matplotlib examples in case any
documentation wants to literal include them
181 changes: 21 additions & 160 deletions doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@
import sphinx
import six
from glob import glob
from sphinx_gallery.sorting import ExplicitOrder

# 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
Expand All @@ -29,14 +28,25 @@

# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['matplotlib.sphinxext.mathmpl', 'sphinxext.math_symbol_table',
'sphinx.ext.autodoc', 'matplotlib.sphinxext.only_directives',
'sphinx.ext.doctest', 'sphinx.ext.autosummary',
'sphinx.ext.inheritance_diagram', 'sphinx.ext.intersphinx',
'sphinx_gallery.gen_gallery',
'matplotlib.sphinxext.plot_directive',
'sphinxext.github', 'sphinxext.custom_roles',
'numpydoc']
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.doctest',
'sphinx.ext.inheritance_diagram',
'sphinx.ext.intersphinx',
'IPython.sphinxext.ipython_console_highlighting',
'IPython.sphinxext.ipython_directive',
'numpydoc', # Needs to be loaded *after* autodoc.
'sphinx_gallery.gen_gallery',
'matplotlib.sphinxext.mathmpl',
'matplotlib.sphinxext.only_directives',
'matplotlib.sphinxext.plot_directive',
'sphinxext.custom_roles',
'sphinxext.github',
'sphinxext.math_symbol_table',
'sphinxext.mock_gui_toolkits',
'sphinxext.skip_deprecated',
]

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

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


_check_deps()

try:
from unittest.mock import MagicMock
except ImportError:
from mock import MagicMock


# Use IPython's console highlighting by default
extensions.extend(['IPython.sphinxext.ipython_console_highlighting',
'IPython.sphinxext.ipython_directive'])
# Import only after checking for dependencies.
from sphinx_gallery.sorting import ExplicitOrder

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


autosummary_generate = True

autodoc_docstring_signature = True
Expand Down Expand Up @@ -334,146 +335,6 @@ def _check_deps():
1),
]


class MyCairo(MagicMock):
version_info = (1, 4, 0)


class MyPyQt4(MagicMock):
class QtGui(object):
# PyQt4.QtGui public classes.
# Generated with
# textwrap.fill([name for name in dir(PyQt4.QtGui)
# if isinstance(getattr(PyQt4.QtGui, name), type)])
_QtGui_public_classes = """\
Display QAbstractButton QAbstractGraphicsShapeItem
QAbstractItemDelegate QAbstractItemView QAbstractPrintDialog
QAbstractProxyModel QAbstractScrollArea QAbstractSlider
QAbstractSpinBox QAbstractTextDocumentLayout QAction QActionEvent
QActionGroup QApplication QBitmap QBoxLayout QBrush QButtonGroup
QCalendarWidget QCheckBox QClipboard QCloseEvent QColor QColorDialog
QColumnView QComboBox QCommandLinkButton QCommonStyle QCompleter
QConicalGradient QContextMenuEvent QCursor QDataWidgetMapper QDateEdit
QDateTimeEdit QDesktopServices QDesktopWidget QDial QDialog
QDialogButtonBox QDirModel QDockWidget QDoubleSpinBox QDoubleValidator
QDrag QDragEnterEvent QDragLeaveEvent QDragMoveEvent QDropEvent
QErrorMessage QFileDialog QFileIconProvider QFileOpenEvent
QFileSystemModel QFocusEvent QFocusFrame QFont QFontComboBox
QFontDatabase QFontDialog QFontInfo QFontMetrics QFontMetricsF
QFormLayout QFrame QGesture QGestureEvent QGestureRecognizer QGlyphRun
QGradient QGraphicsAnchor QGraphicsAnchorLayout QGraphicsBlurEffect
QGraphicsColorizeEffect QGraphicsDropShadowEffect QGraphicsEffect
QGraphicsEllipseItem QGraphicsGridLayout QGraphicsItem
QGraphicsItemAnimation QGraphicsItemGroup QGraphicsLayout
QGraphicsLayoutItem QGraphicsLineItem QGraphicsLinearLayout
QGraphicsObject QGraphicsOpacityEffect QGraphicsPathItem
QGraphicsPixmapItem QGraphicsPolygonItem QGraphicsProxyWidget
QGraphicsRectItem QGraphicsRotation QGraphicsScale QGraphicsScene
QGraphicsSceneContextMenuEvent QGraphicsSceneDragDropEvent
QGraphicsSceneEvent QGraphicsSceneHelpEvent QGraphicsSceneHoverEvent
QGraphicsSceneMouseEvent QGraphicsSceneMoveEvent
QGraphicsSceneResizeEvent QGraphicsSceneWheelEvent
QGraphicsSimpleTextItem QGraphicsTextItem QGraphicsTransform
QGraphicsView QGraphicsWidget QGridLayout QGroupBox QHBoxLayout
QHeaderView QHelpEvent QHideEvent QHoverEvent QIcon QIconDragEvent
QIconEngine QIconEngineV2 QIdentityProxyModel QImage QImageIOHandler
QImageReader QImageWriter QInputContext QInputContextFactory
QInputDialog QInputEvent QInputMethodEvent QIntValidator QItemDelegate
QItemEditorCreatorBase QItemEditorFactory QItemSelection
QItemSelectionModel QItemSelectionRange QKeyEvent QKeyEventTransition
QKeySequence QLCDNumber QLabel QLayout QLayoutItem QLineEdit
QLinearGradient QListView QListWidget QListWidgetItem QMainWindow
QMatrix QMatrix2x2 QMatrix2x3 QMatrix2x4 QMatrix3x2 QMatrix3x3
QMatrix3x4 QMatrix4x2 QMatrix4x3 QMatrix4x4 QMdiArea QMdiSubWindow
QMenu QMenuBar QMessageBox QMimeSource QMouseEvent
QMouseEventTransition QMoveEvent QMovie QPageSetupDialog QPaintDevice
QPaintEngine QPaintEngineState QPaintEvent QPainter QPainterPath
QPainterPathStroker QPalette QPanGesture QPen QPicture QPictureIO
QPinchGesture QPixmap QPixmapCache QPlainTextDocumentLayout
QPlainTextEdit QPolygon QPolygonF QPrintDialog QPrintEngine
QPrintPreviewDialog QPrintPreviewWidget QPrinter QPrinterInfo
QProgressBar QProgressDialog QProxyModel QPushButton QPyTextObject
QQuaternion QRadialGradient QRadioButton QRawFont QRegExpValidator
QRegion QResizeEvent QRubberBand QScrollArea QScrollBar
QSessionManager QShortcut QShortcutEvent QShowEvent QSizeGrip
QSizePolicy QSlider QSortFilterProxyModel QSound QSpacerItem QSpinBox
QSplashScreen QSplitter QSplitterHandle QStackedLayout QStackedWidget
QStandardItem QStandardItemModel QStaticText QStatusBar
QStatusTipEvent QStringListModel QStyle QStyleFactory QStyleHintReturn
QStyleHintReturnMask QStyleHintReturnVariant QStyleOption
QStyleOptionButton QStyleOptionComboBox QStyleOptionComplex
QStyleOptionDockWidget QStyleOptionDockWidgetV2 QStyleOptionFocusRect
QStyleOptionFrame QStyleOptionFrameV2 QStyleOptionFrameV3
QStyleOptionGraphicsItem QStyleOptionGroupBox QStyleOptionHeader
QStyleOptionMenuItem QStyleOptionProgressBar QStyleOptionProgressBarV2
QStyleOptionRubberBand QStyleOptionSizeGrip QStyleOptionSlider
QStyleOptionSpinBox QStyleOptionTab QStyleOptionTabBarBase
QStyleOptionTabBarBaseV2 QStyleOptionTabV2 QStyleOptionTabV3
QStyleOptionTabWidgetFrame QStyleOptionTabWidgetFrameV2
QStyleOptionTitleBar QStyleOptionToolBar QStyleOptionToolBox
QStyleOptionToolBoxV2 QStyleOptionToolButton QStyleOptionViewItem
QStyleOptionViewItemV2 QStyleOptionViewItemV3 QStyleOptionViewItemV4
QStylePainter QStyledItemDelegate QSwipeGesture QSyntaxHighlighter
QSystemTrayIcon QTabBar QTabWidget QTableView QTableWidget
QTableWidgetItem QTableWidgetSelectionRange QTabletEvent
QTapAndHoldGesture QTapGesture QTextBlock QTextBlockFormat
QTextBlockGroup QTextBlockUserData QTextBrowser QTextCharFormat
QTextCursor QTextDocument QTextDocumentFragment QTextDocumentWriter
QTextEdit QTextFormat QTextFragment QTextFrame QTextFrameFormat
QTextImageFormat QTextInlineObject QTextItem QTextLayout QTextLength
QTextLine QTextList QTextListFormat QTextObject QTextObjectInterface
QTextOption QTextTable QTextTableCell QTextTableCellFormat
QTextTableFormat QTimeEdit QToolBar QToolBox QToolButton QToolTip
QTouchEvent QTransform QTreeView QTreeWidget QTreeWidgetItem
QTreeWidgetItemIterator QUndoCommand QUndoGroup QUndoStack QUndoView
QVBoxLayout QValidator QVector2D QVector3D QVector4D QWhatsThis
QWhatsThisClickedEvent QWheelEvent QWidget QWidgetAction QWidgetItem
QWindowStateChangeEvent QWizard QWizardPage QWorkspace
QX11EmbedContainer QX11EmbedWidget QX11Info
"""
for _name in _QtGui_public_classes.split():
locals()[_name] = type(_name, (), {})
del _name


class MySip(MagicMock):
def getapi(*args):
return 1


class MyWX(MagicMock):
class Panel(object):
pass

class ToolBar(object):
pass

class Frame(object):
pass

VERSION_STRING = '2.9'


sys.modules['cairo'] = MyCairo()
sys.modules['cairo'].__name__ = 'cairocffi'
sys.modules['PyQt4'] = MyPyQt4()
sys.modules['sip'] = MySip()
sys.modules['wx'] = MyWX()
sys.modules['wxversion'] = MagicMock()

# numpydoc config

numpydoc_show_class_members = False

# Skip deprecated members

def skip_deprecated(app, what, name, obj, skip, options):
if skip:
return skip
skipped = {"matplotlib.colors": ["ColorConverter", "hex2color", "rgb2hex"]}
skip_list = skipped.get(getattr(obj, "__module__", None))
if skip_list is not None:
return getattr(obj, "__name__", None) in skip_list

def setup(app):
app.connect('autodoc-skip-member', skip_deprecated)
25 changes: 9 additions & 16 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -276,27 +276,20 @@ tutorial in :doc:`/tutorials/introductory/customizing`::

.. literalinclude:: ../../_static/matplotlibrc

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

In the top level :file:`doc` directory there are symlinks pointing to the
Matplotlib :file:`examples`:

.. code-block:: sh

home:~/mpl/doc> ls -l mpl_*
mpl_examples -> ../examples

Plots are included from the examples dir using the symlink:
The examples directory is also copied to :file:`doc/gallery` by sphinx-gallery,
so plots from the examples directory can be included using

.. code-block:: rst

.. plot:: mpl_examples/pylab_examples/simple_plot.py
.. plot:: gallery/pylab_examples/simple_plot.py

Note that the python script that generates the plot is referred to, rather
than any plot that is created. `Sphinx Gallery`_ will provide the incorrect
reference when the documentation is built.
Note that the python script that generates the plot is referred to, rather than
any plot that is created. Sphinx-gallery will provide the correct reference
when the documentation is built.


.. _writing-docstrings:
Expand Down
1 change: 0 additions & 1 deletion doc/mpl_examples
View file
Open in desktop

This file was deleted.

34 changes: 16 additions & 18 deletions doc/sphinxext/math_symbol_table.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,34 +1,34 @@
from __future__ import print_function
symbols = [
["Lower-case Greek",
5,
6,
r"""\alpha \beta \gamma \chi \delta \epsilon \eta \iota \kappa
\lambda \mu \nu \omega \phi \pi \psi \rho \sigma \tau \theta
\upsilon \xi \zeta \digamma \varepsilon \varkappa \varphi
\varpi \varrho \varsigma \vartheta"""],
["Upper-case Greek",
6,
8,
r"""\Delta \Gamma \Lambda \Omega \Phi \Pi \Psi \Sigma \Theta
\Upsilon \Xi \mho \nabla"""],
["Hebrew",
4,
6,
r"""\aleph \beth \daleth \gimel"""],
["Delimiters",
6,
r"""| \{ \lfloor / \Uparrow \llcorner \vert \} \rfloor \backslash
\uparrow \lrcorner \| \langle \lceil [ \Downarrow \ulcorner
\Vert \rangle \rceil ] \downarrow \urcorner"""],
["Big symbols",
5,
6,
r"""\bigcap \bigcup \bigodot \bigoplus \bigotimes \biguplus
\bigvee \bigwedge \coprod \oint \prod \sum \int"""],
["Standard function names",
4,
6,
r"""\arccos \csc \ker \min \arcsin \deg \lg \Pr \arctan \det \lim
\gcd \ln \sup \cot \hom \log \tan \coth \inf \max \tanh
\sec \arg \dim \liminf \sin \cos \exp \limsup \sinh \cosh"""],
["Binary operation and relation symbols",
3,
4,
r"""\ast \pm \slash \cap \star \mp \cup \cdot \uplus
\triangleleft \circ \odot \sqcap \triangleright \bullet \ominus
\sqcup \bigcirc \oplus \wedge \diamond \oslash \vee
Expand Down Expand Up @@ -60,7 +60,7 @@
\Doteq \nsubset \eqcolon \ne
"""],
["Arrow symbols",
2,
4,
r"""\leftarrow \longleftarrow \uparrow \Leftarrow \Longleftarrow
\Uparrow \rightarrow \longrightarrow \downarrow \Rightarrow
\Longrightarrow \Downarrow \leftrightarrow \updownarrow
Expand All @@ -83,7 +83,7 @@
\leftsquigarrow
"""],
["Miscellaneous symbols",
3,
4,
r"""\neg \infty \forall \wp \exists \bigstar \angle \partial
\nexists \measuredangle \eth \emptyset \sphericalangle \clubsuit
\varnothing \complement \diamondsuit \imath \Finv \triangledown
Expand Down Expand Up @@ -111,16 +111,14 @@ def get_n(n, l):
lines.append('')
max_width = max(map(len, syms)) * 2 + 16
header = " " + (('=' * max_width) + ' ') * columns
format = '%%%ds' % max_width
for chunk in get_n(20, get_n(columns, syms)):
lines.append(header)
for part in chunk:
line = []
for sym in part:
line.append(format % (":math:`%s` ``%s``" % (sym, sym)))
lines.append(" " + " ".join(line))
lines.append(header)
lines.append('')
lines.append(header)
for part in get_n(columns, syms):
line = " " + " ".join(
":math:`{0}` ``{0}``".format(sym).rjust(max_width)
for sym in part)
lines.append(line)
lines.append(header)
lines.append('')

state_machine.insert_input(lines, "Symbol table")
return []
Expand Down
Loading