module yamldoc

v0.2.0

Copyright 2014-2015 Sebastiaan Mathôt

http://www.cogsci.nl/smathot

About yamldoc:

• With yamldoc you can take Python docstrings to the next level.
• A systematic YAML-based docstring notation.
• Generates Markdown-formatted documentation for modules, classes, and functions.
• Automatically validate input and output of functions and methods with the @yamldoc.validate decorator.
• Inherit docstrings with the yamldoc.inherit metaclass.

Index:

• module yamldoc
  • class yamldoc.BaseDoc
    • function yamldoc.BaseDoc.__init__(obj, enc=u'utf-8', namePrefix=u'', level=1, customName=None, container=u'span', onlyContents=False, exclude=[])
    • function yamldoc.BaseDoc.__str__()
    • function yamldoc.BaseDoc.__unicode__()
    • function yamldoc.BaseDoc._dict()
    • function yamldoc.BaseDoc._id()
    • function yamldoc.BaseDoc.name()
    • function yamldoc.BaseDoc.stripDict(_dict)
  • function yamldoc.DocFactory(obj, types=[u'function', u'class', u'module', u'property'], *args, **kwargs)
  • class yamldoc.inherit
  • function yamldoc.validate(func)

Example:

import yamldoc

class ExampleClass(object):

    """
    desc:
        This is a description for `ExampleClass`. The docstring is a YAML
        dictionary, where `desc` contains the main description.
    """

    @yamldoc.validate
    def ExampleFunction(self, a, b, c=1, *arglist, **kwdict):

        """
        desc:
            This function accepts only `str` and `unicode` values for `a` and
            only `int` values for `b`. In addition, it accepts an argument list
            and a keyword dictionary.

        example: |
            ExampleFunction('test value')
            ExampleFunction('test value', c=0)

        arguments:
            a:
                desc:   An argument with specific types. These can be checked
                        by the @yamldoc.validate decorator.
                type:   [str, unicode]
            b:          Argument without a specific type. These cannot be
                        checked by the @yamldoc.validate decorator.

        keywords:
            c:
                desc:   A keyword. Keywords are specified in the same way as
                        arguments. The only difference is that they have a
                        default value, which is automatically included in the
                        documentation generated by yamldoc.
                type:   int

        argument-list:
            varargs:    An argument list.

        keyword-dict:
            keywords:   A keyword dictionary.

        returns:
            desc:   Some return value. As for arguments and keywords, you can
                    specify a type, in which case the function output can be
                    checked by the @yamldoc.validate decorator.
            type:   int
        """

        return 1

# Generate and print nicely formatted documentation for ExampleClass
df = yamldoc.DocFactory(ExampleClass)
print df
# Create an instance of ExampleClass
ec = ExampleClass()
# This works, because argument `a` should be string and keyword `b` should int.
ec.ExampleFunction('test', c=10)
# This will give an error, because the argument types do not match the docstring
# specification.
ec.ExampleFunction(10, c='test')

class yamldoc.BaseDoc

The base class from which the other doc classes are derived.

function yamldoc.BaseDoc.__init__(obj, enc=u'utf-8', namePrefix=u'', level=1, customName=None, container=u'span', onlyContents=False, exclude=[])

Constructor. Normally, you don't create a BaseDoc (or one of its derivatives) object directly, but use the DocFactory function.

Arguments:

• obj -- The object to document.

Keywords:

• enc -- The string encoding.
  • Type: str, unicode
  • Default: u'utf-8'
• namePrefix -- A prefix to be pre-pended to the object's name.
  • Type: str, unicode
  • Default: u''
• level -- Describes the header level to be used, so that you can generate formatted documentation.
  • Type: int
  • Default: 1
• customName -- A custom name for the object.
  • Type: str, unicode, None
  • Default: None
• container -- The HTML container type that wraps the documentation. Should be 'div' or 'span'.
  • Type: str, unicode
  • Default: u'span'
• onlyContents -- Indicates whether the full documentation should be generated (False), or only documentation for the child objects (True). This can be useful for documenting the function in a module, without providing any documentation on the module itself.
  • Type: bool
  • Default: False
• exclude -- A list of child objects to exclude. Only applicable to objects that have children, such as classes and modules.
  • Type: list
  • Default: []

function yamldoc.BaseDoc.__str__()

Returns a string representation of the object's documentation.

Returns:

A string representation of the object's documentation.

• Type: str

function yamldoc.BaseDoc.__unicode__()

Returns a unicode string representation of the object's documentation.

Returns:

A unicode string representation of the object's documentation.

• Type: unicode

function yamldoc.BaseDoc._dict()

Generates a dict representation of the object's documentation.

Returns:

A dict representation of the object's documentation.

• Type: dict

function yamldoc.BaseDoc._id()

Returns the object's id, used to link to the object documentation.

Returns:

The object's id.

• Type: unicode

function yamldoc.BaseDoc.name()

Returns the object's name with prefix.

Returns:

The object's name with prefix.

• Type: unicode

function yamldoc.BaseDoc.stripDict(_dict)

Strips whitespace from all str/ unicode values in a dictionary.

Arguments:

• _dict -- The dictionary to strip.
  • Type: dict

Returns:

A stripped dictionary.

• Type: dict

function yamldoc.DocFactory(obj, types=[u'function', u'class', u'module', u'property'], *args, **kwargs)

Creates a type-specific doc object.

Example:

import yamldoc

# Create a type-specific docstring processor for `myFunction`.
df = yamldoc.DocFactory(myFunction)
# Get a markdown-style formatted docstring and print it.
md = unicode(df)
print(md)

Arguments:

• obj -- The object to document.

Keywords:

• types -- A list of types that should be documented.
  • Type: list
  • Default: [u'function', u'class', u'module', u'property']

Argument list:

• *args: See BaseDoc.init for a description of available arguments.

Keyword dict:

• **kwargs: See BaseDoc.init for a description of available keywords.

Returns:

A doc object.

class yamldoc.inherit

A metaclass that inherits docstrings from parent classes.

Example:

# This will make all functions of A inherit the corresponding docstrings
# from B.
import yamldoc
class A(B):
        __metaclass__ = yamldoc.inherit

Source(s):

• http://groups.google.com/group/comp.lang.python/msg/26f7b4fcb4d66c95
• http://stackoverflow.com/questions/8100166/inheriting-methods-docstrings-in-python

function yamldoc.validate(func)

A decorator to validate arguments and return values for a function or method. This decorator allows you to fully specify and check the input and output of a function or method through a properly formatted docstring.

Example:

import yamldoc

@yamldoc.validate
def test(a):

        """
        desc:
                Example function.

        arguments:
                a:
                        desc:   An argument that should be integer.
                        type:   int
                b:
                        desc:   An argument that should be either the value
                                        'x' or 'y'.
                        valid:  [x, y]

        returns:
                desc:           The function should return a boolean.
                type:           bool
        """

        return True

Arguments:

• func -- The function to validate.
  • Type: function, method

[function yamldoc.BaseDoc.__init__(obj, enc=u'utf-8', namePrefix=u'', level=1, customName=None, container=u'span', onlyContents=False, exclude=[])]: #function-__yamldocbasedoc__init____obj-encuutf-8-nameprefixu-level1-customnamenone-containeruspan-onlycontentsfalse-exclude

[function yamldoc.DocFactory(obj, types=[u'function', u'class', u'module', u'property'], *args, **kwargs)]: #function-__yamldocdocfactory__obj-typesufunction-uclass-umodule-uproperty-args-kwargs