This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

Documentation extractor.

Project Description

ExDoc

Documentation extractor.

Extracts pieces of documentation from your code to build a document which can be fed to template processors.

Output can be in JSON, YAML, whatever. Use any command-line templating engine, like j2cli, to render templates from it.

It does not do any automatic background magic: it just offers helpers which allows you to extract the necessary pieces.

Collectors

ExDoc is just a set of helper functions that collects information into dictionaries.

Python

Helpers for Python objects

doc(obj)

Get parsed documentation for an object as a dict.

This includes arguments spec, as well as the parsed data from the docstring.

from exdoc import doc

The doc() function simply fetches documentation for an object, which can be

  • Module
  • Class
  • Function or method
  • Property

The resulting dictionary includes argument specification, as well as parsed docstring:

def f(a, b=1, *args):
    ''' Simple function

    : param a: First
    : type a: int
    : param b: Second
    : type b: int
    : param args: More numbers
    : returns: nothing interesting
    : rtype: bool
    : raises ValueError: hopeless condition
    '''

from exdoc import doc

doc(f)  # ->
{
  'module': '__main__',
  'name': 'f',
  'qualname': 'f',  # qualified name: e.g. <class>.<method>
  'signature': 'f(a, b=1, *args)',
  'qsignature': 'f(a, b=1, *args)',  # qualified signature
  'doc': 'Simple function',
  'clsdoc': '',  # doc from the class (used for constructors)
  # Exceptions
  'exc': [
    {'doc': 'hopeless condition', 'name': 'ValueError'}
  ],
  # Return value
  'ret': {'doc': 'nothing interesting', 'type': 'bool'},
  # Arguments
  'args': [
    {'doc': 'First', 'name': 'a', 'type': 'int'},
    {'default': 1, 'doc': 'Second', 'name': 'b', 'type': 'int'},
    {'doc': 'More numbers', 'name': '*args', 'type': None}
  ],
}

getmembers(obj, *predicates)

Return all the members of an object as a list of (key, value) tuples, sorted by name.

The optional list of predicates can be used to filter the members.

The default predicate drops members whose name starts with ‘_’. To disable it, pass None as the first predicate.

subclasses(cls, leaves=False)

List all subclasses of the given class, including itself.

If leaves=True, only returns classes which have no subclasses themselves.

SqlAlchemy

Documenting SqlAlchemy models.

from exdoc.sa import doc

doc(User)  # ->
{
  'name': 'User',
  # List of tables the model uses
  'table': ('users',),
  'doc': 'User account',
  # PK: tuple[str]
  'primary': ('uid',),
  # Unique keys
  'unique': (
    # tuple[str]
    ('login',),
  ),
  # Foreign keys
  'foreign': (
    {'key': 'uid', 'target': 'users.uid', 'onupdate': None, 'ondelete': 'CASCADE'},
  ),
  # Columns
  'columns': [
    {'key': 'uid', 'type': 'INTEGER NOT NULL', 'doc': ''},
    {'key': 'login', 'type': 'VARCHAR NULL', 'doc': 'Login'},
    {'key': 'creator_uid', 'type': 'INTEGER NULL', 'doc': 'Creator'},
    {'key': 'meta', 'type': 'JSON NULL', 'doc': ''},
  ],
  # Relationships
  'relations': [
    {'key': 'creator', 'model': 'User',
     'target': 'User(creator_uid=uid)', 'doc': ''},
    {'key': 'devices[]', 'model': 'Device',
     'target': 'Device(uid)', 'doc': ''},
    {'key': 'created[]', 'model': 'User',
     'target': 'User(uid=creator_uid)', 'doc': ''},
  ]
}

Building

Create a python file that collects the necessary information and prints json:

#! /usr/bin/env python
from exdoc import doc
import json

from project import User

print json.dumps({
  'user': doc(User),
})

And then use its output:

./collect.py | j2 --format=json README.md.j2
Release History

Release History

This version
History Node

0.0.5-0

History Node

0.0.4-0

History Node

0.0.3-1

History Node

0.0.3-0

History Node

0.0.2-0

History Node

0.0.1-0

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
exdoc-0.0.5_0-py2-none-any.whl (12.6 kB) Copy SHA256 Checksum SHA256 2.7 Wheel Oct 7, 2014
exdoc-0.0.5-0.tar.gz (9.9 kB) Copy SHA256 Checksum SHA256 Source Oct 7, 2014

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting