Metadata-Version: 2.0
Name: exdoc
Version: 0.0.2-0
Summary: Documentation extractor. 
Home-page: https://github.com/kolypto/py-exdoc
Author: Mark Vartanyan
Author-email: kolypto@gmail.com
License: BSD
Keywords: documentation
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: _dev
Requires-Dist: wheel; extra == '_dev'
Requires-Dist: nose; extra == '_dev'
Requires-Dist: sqlalchemy; extra == '_dev'
Requires-Dist: j2cli; extra == '_dev'

|Build Status|

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 <https://github.com/kolypto/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.

.. code:: python

    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:

.. code:: python

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

.. code:: python

    from exdoc.sa import doc

    doc(User)  # ->
    {
      'name': 'User',
      'table': 'users',
      'doc': 'User account',
      # PK: str of tuple[str]
      'primary': 'uid',
      # Unique keys
      'unique': [
        # str or tuple[str]
        'login',
      ],
      # Foreign keys
      'foreign': [
        {'key': 'uid', 'target': 'users.uid'},
      ],
      # 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:

.. code:: python

    #! /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:

.. code:: console

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

.. |Build Status| image:: https://api.travis-ci.org/kolypto/py-exdoc.png?branch=master
   :target: https://travis-ci.org/kolypto/py-exdoc


