A Python Documentation API for Developers
Pull request Compare This branch is 1 commit behind codebrowse:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
docs
test
.gitignore
.travis.yml
LICENSE
README.md
press.jpg
setup.py
test.sh
test_readme.py

README.md

Build Status

Python Docs

A Python Documentation API for Developers

Michael Van Veen

Machine Simple

Abstract

Python has wonderful, first-class support for documentation. Unfortunately, this incredibly thoughtful feature of the language is hidden behind large, monolithic suites or outdated, unsupported pieces of spaghetti. Up until now, we haven't had easy programatic access to our source code and documentation.

No longer. Docs is a Python Documentation API I for Developers. Our language is dynamic. It's time for our documentation to start acting like it.

Warning

It is early days for this project. There is still a lot of stuff to be done. Among those are several security concerns. Most importantly, note that Python Docs will import the modules and objects you throw at it (and probably will for a long time), so please only use it with modules that you trust!

Examples

Modules

>>> from docs.modules import Module
>>> m = Module(filename='docs/modules/module.py')
>>> m
<[Module] docs/modules/module.py>

Authors

>>> import docs
>>> d = docs.get(docs)
>>> d.authors
['Michael Van Veen (michael@mvanveen.net)']

Docstrings

>>> m.docstring
'Wrapper object for Python modules'

Version

 >>> d = docs.get(docs)
 >>> d.version
 ['0.1']

Copyright

 >>> d = docs.get(docs)
 >>> d.copyright
 ['Copyright 2012, Michael Van Veen']

Maintainers

>>> d = docs.get(docs)
>>> d.maintainers
['Michael Van Veen (michael@mvanveen.net)']

Status

>>> d = docs.get(docs)
>>> d.status
['Beta']

Filename

>>> d = docs.get(docs)
>>> d.filename
'docs/__init__.py'

Functions

Top-level accessor

>>> import docs
>>> len(docs.get_functions(docs))
4

Object Attributes

The functions attribute is defined for Function, Module, and Class.

>>> d = docs.get(docs)
>>> d.functions
[<[Function] get>, <[Function] get_imports>, <[Function] get_functions>, <[Function] get_classes>]

Imports

Top-level accessor

>>> import docs
>>> docs.get_imports(docs)
[<[Import] ast>, <[Import] inspect>, <[Import] os>, <[Import] sys>, <[ImportFrom] docs.classes.Class>, <[ImportFrom] docs.function.Function>, <[ImportFrom] docs.imports.Import>, <[ImportFrom] docs.visitors.Node>, <[ImportFrom] docs.modules.Module>, <[ImportFrom] docs.package.Package>]

Object Attributes

>>> d = docs.get(docs)
>>> len(d.imports)
10

Classes

Top-level accessor

>>> import docs
>>> docs.get_classes('ast')
[<[Class] NodeVisitor>, <[Class] NodeTransformer>]

Object Attributes

>>> d = docs.get('ast')
>>> d.classes
[<[Class] NodeVisitor>, <[Class] NodeTransformer>]

Coming soon:

  • Variables
  • python paths and filenames across all

Nice to haves:

  • Support for Statement and Expression
  • Dynamic import hooks
  • comments
  • TODOS
  • JSON API?
  • ???
  • Profit

Influences

License

Source code is MIT licensed. Documentation is creative commons .

--mvv