Creates RestructuredText-based documentation for Python
modules and docstrings by parsing AbstractSyntaxTrees generated by
the Python compiler.
- Imports:
- compiler, docutils, docutils.core, docutils.nodes, docutils.utils, glob, itertools, os, os.path, rstdoc.misclibs.functional, rstdoc.misclibs.util, rstdoc.rstlib.astwriter, sys, textwrap, traceback, types, unittest
- Classes:
- Attribute(NodeVisitor): An Attribute instance is created for each
top-level assignment statement.
- Class(NodeVisitor): A Class instance is created for each class
definition.
- Decorator(NodeVisitor): A Decorator instance is created for each decorater
of a method.
- Global(NodeVisitor): A Global instance is created for each global
statement.
- Import(NodeVisitor): An Import instance is created for each imported
module.
- Method(NodeVisitor): A Method instance is created for each method
definition.
- Module(NodeVisitor): An instance of Module is created at the top level
of the node tree. Use the documentString or
documentFile methods to create me.
- NodeVisitor(object): I am the base for all visitor subclasses. These
classes should not be created individually. Use
the documentFile or documentString methods instead.
- Methods:
- docString(docstring, n=0, signature=None): I return a list of docutils paragraph nodes
for the specified docstring. The '''n'''
argument specifies the maximum number of paragraphs
that will be returned.
- documentError(title, includeTraceback=True): Format an exception.
- documentFile(name): I perform the same operations as documentModule
except I am passed a filename instead of the module
source.
- documentPackages(docPath, packages, writer_name='html', output=sys.stderr, title='Package Index', settings={ }): Document one or more packages, writing documentaion
to docPath with docutils writer writer_name. Status
messages are printed to file object output, set output
to None to suppress messages. The title argument sets
the doctree["title"] attribute and also sets the
heading of the index.
- documentString(source, name='<string>'): Create a tree of NodeVisitor subclasses.
The instances have some usefull properties and
the docTree method can be used to generate
a docutils document tree which can be used to
generate HTML/LATEX documentation.
- moduleDocString(source, n=0, name=None): I attempt to parse the module docString from
source. If any error occurs then None is returned.
Otherwise I will return the first n paragraphs of the
modules docstring. If n is 0 then all paragraphs are
returned.
- overrideSettings(kw):
- publish_doctree(*args, **kw):
- publish_from_doctree(*args, **kw):
- setDocStringFilter(filter): Use me to define a function that it is applied
to docstrings before they are processed.
- testSuite():
- Attributes:
- _filter = None
- test1 = '- This is Junk -'
- test2 = "\n''' module.py\n\nThis is documentation.\n\nThis is too.\n'''\n"
Back to astdoc
- Bases:
- NodeVisitor
An Attribute instance is created for each
top-level assignment statement.
- Methods:
- __init__(self, name, lineNo, docstring): I create an Attribute instance.
- Attributes:
- _typeName = 'Attribute'
Back to astdoc.Attribute
- Arguments:
- self, name, lineNo, docstring
I create an Attribute instance.
- name: string
- The attribute name.
- lineNo: int
- The line number where the assignment was made.
- docstring: string
- A docstring is created from the entire
assignment statement.
Back to astdoc
- Bases:
- NodeVisitor
A Class instance is created for each class
definition.
- Classes:
- bases(Property): The class bases.
- Methods:
- __init__(self, node): Create a Class instance.
- Attributes:
- _typeName = 'Class'
Back to astdoc.Class
- Arguments:
- self, node
Create a Class instance.
- node: node
- The node of the class definition.
Back to astdoc
- Bases:
- NodeVisitor
A Decorator instance is created for each decorater
of a method.
- Methods:
- __init__(self, node): I create a Method instance.
- Attributes:
- _typeName = 'Decorator'
Back to astdoc
- Bases:
- NodeVisitor
A Global instance is created for each global
statement.
- Methods:
- __init__(self, name, lineNo): Create an Global instance.
- Attributes:
- _typeName = 'Global'
Back to astdoc.Global
- Arguments:
- self, name, lineNo
Create an Global instance.
- name: string
- The name of the global variable.
- lineNo: int
- The line number of the global statement.
Back to astdoc
- Bases:
- NodeVisitor
An Import instance is created for each imported
module.
- Methods:
- __init__(self, name, lineNo): Create an Import instance.
- Attributes:
- _typeName = 'Import'
Back to astdoc.Import
- Arguments:
- self, name, lineNo
Create an Import instance.
- name: string
- The name of the imported module.
- lineNo: int
- The line number of the import/from statement.
Back to astdoc
- Bases:
- NodeVisitor
A Method instance is created for each method
definition.
- Methods:
- __init__(self, node): I create a Method instance.
- visitAssign(self, node): I am a no-op (we do not want to see
assignments to local variables.)
- Attributes:
- _typeName = 'Method'
Back to astdoc.Method
- Arguments:
- self, node
I create a Method instance.
- node: compiler.ast.node
- The node instance.
Back to astdoc
- Bases:
- object
I am the base for all visitor subclasses. These
classes should not be created individually. Use
the documentFile or documentString methods instead.
The only public method of this class is
docTree. The remaining methods are called
by the node walker.
- Classes:
- docstring(Property): The node's docstring.
- lineno(Property): The source line defining the node.
- name(Property): The name of the node.
- nodeMap(Property): Maps nodes to names.
- signature(Property): The bases/arguments used to define the node.
- typeName(Property): The type of node: Module, Class,...
- Methods:
- __init__(self, name, lineno=None, signature=None, docstring=None, node=None): Create a NodeVisitor instance.
- _docTree(self, prefix=''): I create a section for the current node,
recursively calling all children as required.
- _get(self, attr):
- _hasChildren(self): Returns True if the node has any children.
- _hasDocstring(self): Returns True if the node has any children.
- docTree(self): Create a docutils document tree for the
current instance.
- visitAssign(self, node):
- visitClass(self, node):
- visitFrom(self, node):
- visitFunction(self, node):
- visitGlobal(self, node):
- visitImport(self, node):
- visitModule(self, node):
- Attributes:
- _typeName = None
- attributes = property(fget = lambda self: self._get('_attributes'))
- classes = property(fget = lambda self: self._get('_classes'))
- decorators = property(fget = lambda self: self._get('_decorators'))
- globals = property(fget = lambda self: self._get('_globals'))
- hasChildren = property(fget = lambda self: self._hasChildren())
- hasDocstring = property(fget = lambda self: self._hasDocstring())
- imports = property(fget = lambda self: self._get('_imports'))
- methods = property(fget = lambda self: self._get('_methods'))
Back to astdoc.NodeVisitor
- Bases:
- Property
The type of node: Module, Class,...
- Methods:
- fget(self, instance):
- Attributes:
- fset = fdel = None
Back to astdoc.NodeVisitor
- Arguments:
- self, name, lineno=None, signature=None, docstring=None, node=None
Create a NodeVisitor instance.
- name: string
- The name of the module to document (only
used for reference).
- lineno: int
- The line number of the source which defines
the node.
- signature: string
- The signature of the node, def foo(bar),
for example.
- docstring: string
- The nodes docstring.
- node: node
- The Ast node of the current item. See the
standard library compiler module.
Back to astdoc.NodeVisitor
- Arguments:
- self, prefix=''
I create a section for the current node,
recursively calling all children as required.
- prefix: string
- The part of the full dotted name prior to
the current node. For example, if the current
node is myMethod of MyClass in themodule then
the prefix would be "themodule.MyClass.".
- Methods:
- defList(term, *defs): I create a definition list.
- definition(node):
- link(node): I create a definition list definition
with a link.
- paragraph(text): I create a definition list definition
with a paragraph of text.
Back to astdoc
- Arguments:
- docstring, n=0, signature=None
I return a list of docutils paragraph nodes
for the specified docstring. The '''n'''
argument specifies the maximum number of paragraphs
that will be returned.
Use the method setDocString filter to "wikify" or
otherwise process the docstring by replacing string
patterns with reStructured text roles or other text.
>>> print docString("")
[<paragraph: >]
>>> print docString("testme1\n\n\ntestme2")
[<paragraph: <#text: u'testme1'>>,
<paragraph: <#text: u'testme2'>>]
>>> print docString("testme1\n\n\ntestme2", 1)
[<paragraph: <#text: u'testme1'>>]
Back to astdoc
- Arguments:
- title, includeTraceback=True
Format an exception.
>>> try:
... raise ValueError("oops")
... except:
... print publish_from_doctree(
... documentError("Sample Error"))
<document source="Sample Error">
<error>
<definition_list>
<definition_list_item>
<term>
Sample Error
<definition>
<paragraph>
oops
<literal_block xml:space="preserve">
Traceback (most recent call last):
...
ValueError: oops
<BLANKLINE>
Back to astdoc
- Arguments:
- name
I perform the same operations as documentModule
except I am passed a filename instead of the module
source.
- name: string
- The filename of the module. This file is
read to obtain the source for the module.
- returns: Module
- The returned object is an instance of Module.
Back to astdoc
- Arguments:
- docPath, packages, writer_name='html', output=sys.stderr, title='Package Index', settings={ }
Document one or more packages, writing documentaion
to docPath with docutils writer writer_name. Status
messages are printed to file object output, set output
to None to suppress messages. The title argument sets
the doctree["title"] attribute and also sets the
heading of the index.
- Methods:
- addFile(moduleName, docs):
- addModule(moduleDocs, docs):
- defList(term, *defs): Create a definition list
- writeDocs(path, docTree):
Back to astdoc
- Arguments:
- source, name='<string>'
Create a tree of NodeVisitor subclasses.
The instances have some usefull properties and
the docTree method can be used to generate
a docutils document tree which can be used to
generate HTML/LATEX documentation.
- source: string
- The source code of the module.
- name: string
- The name of the module to document (only
used for reference purposes).
- returns: Module
- The returned object is an instance of Module.
Back to astdoc
- Arguments:
- source, n=0, name=None
I attempt to parse the module docString from
source. If any error occurs then None is returned.
Otherwise I will return the first n paragraphs of the
modules docstring. If n is 0 then all paragraphs are
returned.
>>> print moduleDocString(test1)
None
>>> print moduleDocString(test2)
[<paragraph: <#text: u'module.py'>>,
<paragraph: <#text: u'This is document ...'>>,
<paragraph: <#text: u'This is too.'>>]
>>> print moduleDocString(test2, 2)
[<paragraph: <#text: u'module.py'>>,
<paragraph: <#text: u'This is document ...'>>]
- Classes:
- ModuleVisitor(object):
Back to astdoc.moduleDocString
- Bases:
- object
- Methods:
- __init__(self, source):
- visitModule(self, node):
- Attributes:
- docString = property(fget = lambda self: docString(self._docstring, n))
Back to astdoc
- Arguments:
- filter
Use me to define a function that it is applied
to docstrings before they are processed.
>>> def caps(string): return string.upper()
>>> setDocStringFilter(caps)
>>> print docString("testme1\n\n\ntestme2")
[<paragraph: <#text: u'TESTME1'>>, <paragraph: <#text: u'TESTME2'>>]
>>> setDocStringFilter(None)
>>> print docString("testme1\n\n\ntestme2")
[<paragraph: <#text: u'testme1'>>, <paragraph: <#text: u'testme2'>>]
- Globals:
- _filter