Return to index

Module rstdoc.rstlib.astdoc


Module astdoc

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"

Class astdoc.Attribute

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'

Method astdoc.Attribute.__init__

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.

Class astdoc.Class

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'

Method astdoc.Class.__init__

Back to astdoc.Class

Arguments:
self, node

Create a Class instance.

node: node
The node of the class definition.

Class astdoc.Decorator

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'

Method astdoc.Decorator.__init__

Back to astdoc.Decorator

Arguments:
self, node

I create a Method instance.

node: node
The node of the def statement.

Class astdoc.Global

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'

Method astdoc.Global.__init__

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.

Class astdoc.Import

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'

Method astdoc.Import.__init__

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.

Class astdoc.Method

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'

Method astdoc.Method.__init__

Back to astdoc.Method

Arguments:
self, node

I create a Method instance.

node: compiler.ast.node
The node instance.

Class astdoc.Module

Back to astdoc

Bases:
NodeVisitor

An instance of Module is created at the top level of the node tree. Use the documentString or documentFile methods to create me.

Methods:
__init__(self, source, name='<string>'): Create a Module instance.
Attributes:
_typeName = 'Module'

Method astdoc.Module.__init__

Back to astdoc.Module

Arguments:
self, source, name='<string>'

Create a Module instance.

source: string
The source code for the module.
name: string
The name of the module for reference only.

Class astdoc.NodeVisitor

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'))

Class astdoc.NodeVisitor.typeName

Back to astdoc.NodeVisitor

Bases:
Property

The type of node: Module, Class,...

Methods:
fget(self, instance):
Attributes:
fset = fdel = None

Method astdoc.NodeVisitor.__init__

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.

Method astdoc.NodeVisitor._docTree

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.

Method astdoc.NodeVisitor._get

Back to astdoc.NodeVisitor

Arguments:
self, attr
Methods:
include(item):

Method astdoc.docString

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'>>]

Method astdoc.documentError

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>

Method astdoc.documentFile

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.

Method astdoc.documentPackages

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):

Method astdoc.documentString

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.

Method astdoc.moduleDocString

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):

Class astdoc.moduleDocString.ModuleVisitor

Back to astdoc.moduleDocString

Bases:
object
Methods:
__init__(self, source):
visitModule(self, node):
Attributes:
docString = property(fget = lambda self: docString(self._docstring, n))

Method astdoc.setDocStringFilter

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

Method astdoc.testSuite

Back to astdoc

Arguments:
Imports:
astdoc, doctest