r"""
======
mmfext
======
Sphinx extension that allows me to perform some preprocessing. The
following features are added:
LaTeX Math
==========
Documentation included by :mod:`sphinx.ext.autodoc` is parsed and
dollar signs are replaced: ``\$...\$ -> ``:math:\`...\```. This
allows me to use more LaTeX syntax for example, so my documentation
can be kept closer to the LaTeX source. To allow dollar signs to be used in
matplotlib, we do *not* touch dollar signs directly preceded or followed by a
quotation: ``'$``, ``$'``, ``"$``, or ``$"``.
.. todo:: Provide some mechanism for detecting dollar signs in
:mod:`matplotlib` labels where they should not be replaced. For
example, in `.. plot::` directives and in code examples..
Member Filtering
================
Additional member filtering options are provided. This allows one to
include private members in the documentation for example. In
particular, if a member is included in `__all__` or
`__documented_members__`, then it will always be included in the
documentation.
"""
import re
import mmf.objects
from mmf.objects._objects import _get_signature as mmf_objects_get_signature
[docs]def preprocess(app, docname, source):
r"""This will be called when the source is read, allowing
preprocessing.
Examples
--------
>>> def replace(s):
... src = [s]
... preprocess(None, None, src)
... return src[0]
>>> replace('$x=3$') # Standard replacement
':math:`x=3`'
>>> replace('$x=3$ $y=4$') # Replaces all equations
':math:`x=3` :math:`y=4`'
>>> replace('"$x$"') # Does not touch quoted equations
'"$x$"'
>>> replace("'$x$'")
"'$x$'"
>>> replace('\$x\$') # Converts \$ -> $
'$x$'
"""
# This matches '$<stuff>$' where <stuff> has at least one entry
LaTeX_math_regexp = re.compile(r"""
(?<!['"\$\\]) # Must not be preceded by a \, quote, or another $
\$ # The initial $
([^'"\$] # Following character must not be a quote or $
[^\$]*?) # Pattern must have no $.
\$ # The final $
(?!['"]) # must not be followed by a quote
""",
re.VERBOSE)
if '$' in source[0]:
source[0] = LaTeX_math_regexp.sub(r":math:`\1`",
source[0]).replace(r'\$', r'$')
[docs]def autodoc_preprocess_docstring(app, what, name, obj, options, lines):
r"""This will be called once autodoc has generated the
docstring for an object."""
source = ["\n".join(lines)]
if '$' in source[0]:
preprocess(app, name, source)
del lines[:]
lines.extend(source[0].splitlines())
[docs]def autodoc_process_signature(app, what, name, obj, options, signature,
return_annotation):
r"""Process signature of :class:`mmf.objects.StateVars` subclasses
which have a generic signature by default."""
if 'class' == what and issubclass(obj, mmf.objects.StateVars):
signature = mmf_objects_get_signature(obj._state_vars)
return (signature, return_annotation)
[docs]def autodoc_skip_member(app, what, name, obj, skip, options):
r"""Emitted when autodoc has to decide whether a member should be
included in the documentation. The member is excluded if a handler
returns True. It is included if the handler returns False.
Parameters
----------
app :
the Sphinx application object
what : "module", "class", "exception", "function", "method", "attribute"
The type of the object which the docstring belongs to.
name :
The fully qualified name of the object
obj :
The object itself
skip : bool
A boolean indicating if autodoc will skip this member if the
user handler does not override the decision.
options :
The options given to the directive: an object with attributes
`inherited_members`, `undoc_members`, `show_inheritance` and `noindex`
that are `True` if the flag option of same name was given to the
auto directive.
"""
if (name in list(getattr(obj, '__all__', []))
+ list(getattr(obj, '__documented_members__', []))):
return True
else:
return skip
[docs]def setup(app):
r"""The guts of the extension."""
# I need the autodoc extension.
app.setup_extension('sphinx.ext.autodoc')
app.connect('source-read', preprocess)
app.connect('autodoc-process-docstring', autodoc_preprocess_docstring)
#app.connect('autodoc-process-signature', autodoc_process_signature)
app.connect('autodoc-skip-member', autodoc_skip_member)