Commit 5e975444 authored by Tiago Peixoto's avatar Tiago Peixoto
Browse files

Cosmetic documentation changes

parent 72bd25b3
.. automodule:: graph_tool .. automodule:: graph_tool
:members: :members:
.. autoclass:: GraphView
:show-inheritance:
.. autoclass:: PropertyArray
:show-inheritance:
:members: prop_map
Available subpackages Available subpackages
===================== =====================
......
"""
========
numpydoc
========
Sphinx extension that handles docstrings in the Numpy standard format. [1]
It will:
- Convert Parameters etc. sections to field lists.
- Convert See Also section to a See also entry.
- Renumber references.
- Extract the signature from the docstring, if it can't be determined otherwise.
.. [1] http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines#docstring-standard
"""
import os, re, pydoc
from docscrape_sphinx import get_doc_object, SphinxDocString
import inspect
def mangle_docstrings(app, what, name, obj, options, lines,
reference_offset=[0]):
if what == 'module':
# Strip top title
title_re = re.compile(r'^\s*[#*=]{4,}\n[a-z0-9 -]+\n[#*=]{4,}\s*',
re.I|re.S)
lines[:] = title_re.sub('', "\n".join(lines)).split("\n")
else:
doc = get_doc_object(obj, what)
lines[:] = str(doc).split("\n")
if app.config.numpydoc_edit_link and hasattr(obj, '__name__') and \
obj.__name__:
if hasattr(obj, '__module__'):
v = dict(full_name="%s.%s" % (obj.__module__, obj.__name__))
else:
v = dict(full_name=obj.__name__)
lines += ['', '.. htmlonly::', '']
lines += [' %s' % x for x in
(app.config.numpydoc_edit_link % v).split("\n")]
# replace reference numbers so that there are no duplicates
references = []
for l in lines:
l = l.strip()
if l.startswith('.. ['):
try:
references.append(int(l[len('.. ['):l.index(']')]))
except ValueError:
print "WARNING: invalid reference in %s docstring" % name
# Start renaming from the biggest number, otherwise we may
# overwrite references.
references.sort()
if references:
for i, line in enumerate(lines):
for r in references:
new_r = reference_offset[0] + r
lines[i] = lines[i].replace('[%d]_' % r,
'[%d]_' % new_r)
lines[i] = lines[i].replace('.. [%d]' % r,
'.. [%d]' % new_r)
reference_offset[0] += len(references)
def mangle_signature(app, what, name, obj, options, sig, retann):
# Do not try to inspect classes that don't define `__init__`
if (inspect.isclass(obj) and
'initializes x; see ' in pydoc.getdoc(obj.__init__)):
return '', ''
if not (callable(obj) or hasattr(obj, '__argspec_is_invalid_')): return
if not hasattr(obj, '__doc__'): return
doc = SphinxDocString(pydoc.getdoc(obj))
if doc['Signature']:
sig = re.sub("^[^(]*", "", doc['Signature'])
return sig, ''
def initialize(app):
try:
app.connect('autodoc-process-signature', mangle_signature)
except:
monkeypatch_sphinx_ext_autodoc()
def setup(app, get_doc_object_=get_doc_object):
global get_doc_object
get_doc_object = get_doc_object_
app.connect('autodoc-process-docstring', mangle_docstrings)
app.connect('builder-inited', initialize)
app.add_config_value('numpydoc_edit_link', None, True)
#------------------------------------------------------------------------------
# Monkeypatch sphinx.ext.autodoc to accept argspecless autodocs (Sphinx < 0.5)
#------------------------------------------------------------------------------
def monkeypatch_sphinx_ext_autodoc():
global _original_format_signature
import sphinx.ext.autodoc
if sphinx.ext.autodoc.format_signature is our_format_signature:
return
print "[numpydoc] Monkeypatching sphinx.ext.autodoc ..."
_original_format_signature = sphinx.ext.autodoc.format_signature
sphinx.ext.autodoc.format_signature = our_format_signature
def our_format_signature(what, obj):
r = mangle_signature(None, what, None, obj, None, None, None)
if r is not None:
return r[0]
else:
return _original_format_signature(what, obj)
...@@ -230,8 +230,7 @@ class PropertyArray(numpy.ndarray): ...@@ -230,8 +230,7 @@ class PropertyArray(numpy.ndarray):
class PropertyMap(object): class PropertyMap(object):
"""This class provides a mapping from vertices, edges or whole graphs to """This class provides a mapping from vertices, edges or whole graphs to arbitrary properties.
arbitrary properties.
The possible property types are listed below. The possible property types are listed below.
...@@ -282,17 +281,18 @@ class PropertyMap(object): ...@@ -282,17 +281,18 @@ class PropertyMap(object):
return self.__map[self.__key_trans(k)] return self.__map[self.__key_trans(k)]
def __setitem__(self, k, v): def __setitem__(self, k, v):
key = self.__key_trans(k)
try: try:
self.__map[self.__key_trans(k)] = v self.__map[key] = v
except TypeError: except TypeError:
# attempt to convert to a compatible python type. This is useful, # attempt to convert to a compatible python type. This is useful,
# for instance, when dealing with numpy scalar types. # for instance, when dealing with numpy scalar types.
valtype = self.python_value_type() valtype = self.python_value_type()
if isistance(valtype, tuple): if isinstance(valtype, tuple):
val = [valtype[1](x) for x in v] val = [valtype[1](x) for x in v]
else: else:
val = valtype(v) val = valtype(v)
self.__map[self.__key_trans(k)] = val self.__map[key] = val
def __repr__(self): def __repr__(self):
# provide some more useful information # provide some more useful information
...@@ -408,8 +408,7 @@ def _check_prop_vector(prop, name=None, scalar=True, floating=False): ...@@ -408,8 +408,7 @@ def _check_prop_vector(prop, name=None, scalar=True, floating=False):
def group_vector_property(props, value_type=None, vprop=None, pos=None): def group_vector_property(props, value_type=None, vprop=None, pos=None):
"""Group list of properties ``props`` into a vector property map of the same """Group list of properties ``props`` into a vector property map of the same type.
type.
Parameters Parameters
---------- ----------
...@@ -476,8 +475,7 @@ def group_vector_property(props, value_type=None, vprop=None, pos=None): ...@@ -476,8 +475,7 @@ def group_vector_property(props, value_type=None, vprop=None, pos=None):
def ungroup_vector_property(vprop, pos, props=None): def ungroup_vector_property(vprop, pos, props=None):
"""Ungroup vector property map ``vprop`` into a list of individual property """Ungroup vector property map ``vprop`` into a list of individual property maps.
maps.
Parameters Parameters
---------- ----------
...@@ -1232,9 +1230,12 @@ class Graph(object): ...@@ -1232,9 +1230,12 @@ class Graph(object):
def load_graph(file_name, file_format="auto"): def load_graph(file_name, file_format="auto"):
"""Load a graph from ``file_name`` (which can be either a string or a """
file-like object). The format is guessed from ``file_name``, or can be Load a graph from ``file_name`` (which can be either a string or a file-like object).
specified by ``file_format``, which can be either "xml" or "dot"."""
The format is guessed from ``file_name``,
or can be specified by ``file_format``, which can be either "xml" or "dot".
"""
g = Graph() g = Graph()
g.load(file_name, file_format=file_format) g.load(file_name, file_format=file_format)
return g return g
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment