logo

Jinja24Doc for Python

Lightweight documentation generator with jinja2 templates.
About Tools Templates Api Reference Licence GitHub Issues PyPI

jinja24doc

apidoc

key_doc

local_name

pep_rfc

property_info

rst

wiki

context

log

frontend

auto_cmdline

build_parser

embed_stylesheet

jinja_cmdline

process

verbose

module jinja24doc link | top

Jinja24doc is lightweight documentation generator for python modules with jinja2 templates. It is part of Poor Http group tools (WSGI connector, WSGI/HTTP Server and mod_python connector). It could load modules and gets documentation for its items. No configuration is needed, only jinja2 templates. Your or from jinja2doc package.
Module dependences: apidoc , context , rst , wiki

module apidoc link | top

module api documentation reader
Module dependences: inspect , operator , re , re , sys

class ApiDoc link | top

def keywords(self, api, api_url='', types=('module', 'class', 'method', 'staticmethod', 'descriptor', 'property', 'variable', 'function', 'h1', 'h2', 'h3')) link | top

Fill internal api_url variable from names of modules, classes, functions, methods, variables or h1, h2 and h3 sections. With this, wiki can create links to this functions or classes. 
    {% set api = load_module('module') %}

    {# create api rexex for from module where api will be on
       module_api.html #}
    {% do keywords(api, 'module_api.html') %}

    {# create api rexex from module where api will be on same page #}
    {% do keywords(api) %}

    {# another way how to call keywords function without do keyword #}
    {{ keywords(api) }}    {# keywords function return empty string #}
Nice to have: there could be nice, if will be arguments in title, so mouseover event show some little detail of functions, methods or variables.

def linked_api(self, doc) link | top

Append link to api to html.

Function is called by Context.wiki or Context.rst.

def load_module(self, module) link | top

Get documentation of function, variables and classes from module.

Example: 
    {% set api = load_module('module') %}
    {% for type, name, args, doc = api[0] %}
        ...

def uni(self, text) link | top

Function always return unicode in Python 2 or str in Python 3.

class Fn link | top

Support class for naming in module.

def key_doc(a) link | top

Return string sortable item via ordering keys.

def local_name(name) link | top

Returns striped name from its parent (module or class).

Typical use: 
    {{ local_name('MyClass.__init__') }} {# put __init__ to document #}

def pep_rfc(doc) link | top

Automatic create html links in doc from PEP and RFC notifications.

def property_info(info, delimiter=' | ') link | top

Returns property info from tupple.

Input tuple must containts flags if property is writable, readable and deletable. 
    {# return someone like this: WRITE | READ | DELETE #}
    {{ property_info(info) }}

module rst link | top

Library for reStrucuredText parsing, and generating simple HTML output.
Module dependences: docutils.core , docutils_tinyhtml , jinja24doc.apidoc , jinja24doc.wiki , os

class Rst link | top

Class based on ApiDoc.

def keywords(self, api, api_url='', types=('module', 'class', 'method', 'staticmethod', 'descriptor', 'property', 'variable', 'function', 'h1', 'h2', 'h3')) link | top

Fill internal api_url variable from names of modules, classes, functions, methods, variables or h1, h2 and h3 sections. With this, wiki can create links to this functions or classes. 
    {% set api = load_module('module') %}

    {# create api rexex for from module where api will be on
       module_api.html #}
    {% do keywords(api, 'module_api.html') %}

    {# create api rexex from module where api will be on same page #}
    {% do keywords(api) %}

    {# another way how to call keywords function without do keyword #}
    {{ keywords(api) }}    {# keywords function return empty string #}
Nice to have: there could be nice, if will be arguments in title, so mouseover event show some little detail of functions, methods or variables.

def linked_api(self, doc) link | top

Append link to api to html.

Function is called by Context.wiki or Context.rst.

def load_module(self, module) link | top

Get documentation of function, variables and classes from module.

Example: 
    {% set api = load_module('module') %}
    {% for type, name, args, doc = api[0] %}
        ...

def load_rst(self, rstfile, link='link', top='top', system_message=False) link | top

Load reStructuredText file and create docs list of headers and text.

Parameters:
rstfile - string, reStructured source file name (readme.rst)
link - link label for headers. If is empty, link href will be
hidden.
top - top label for headers. If is empty, top href will be hidden. 
    {% set sections = load_rst('readme.rst', '', '') %}
    {% type, filename, _none_, text = sections[-1] %}

def rst(self, doc, link='link', top='top', title='__doc__', section_level=2, system_message=False) link | top

Call reStructuredText docutil parser for doc and return it with html representation of reStructuredText formating. For more details see http://docutils.sourceforge.net/rst.html.

def uni(self, text) link | top

Function always return unicode in Python 2 or str in Python 3.

module wiki link | top

Module dependences: builtins , inspect , jinja2.runtime , jinja24doc.apidoc , os , re , sys

class Wiki link | top

def keywords(self, api, api_url='', types=('module', 'class', 'method', 'staticmethod', 'descriptor', 'property', 'variable', 'function', 'h1', 'h2', 'h3')) link | top

Fill internal api_url variable from names of modules, classes, functions, methods, variables or h1, h2 and h3 sections. With this, wiki can create links to this functions or classes. 
    {% set api = load_module('module') %}

    {# create api rexex for from module where api will be on
       module_api.html #}
    {% do keywords(api, 'module_api.html') %}

    {# create api rexex from module where api will be on same page #}
    {% do keywords(api) %}

    {# another way how to call keywords function without do keyword #}
    {{ keywords(api) }}    {# keywords function return empty string #}
Nice to have: there could be nice, if will be arguments in title, so mouseover event show some little detail of functions, methods or variables.

def linked_api(self, doc) link | top

Append link to api to html.

Function is called by Context.wiki or Context.rst.

def load_module(self, module) link | top

Get documentation of function, variables and classes from module.

Example: 
    {% set api = load_module('module') %}
    {% for type, name, args, doc = api[0] %}
        ...

def load_source(self, srcfile, code='python') link | top

Load source and format them as code 
    {{ load_source('example.py') }}
    {{ load_source('example.ini', 'ini') }}

def load_text(self, textfile) link | top

Deprecated alias for Wiki.load_wiki.

def load_wiki(self, textfile, link='link', top='top') link | top

Load file and create docs list of headers and texts.
textfile - string, text file name (manual.txt)
link - link label for headers. If is empty, link href will be
hidden.
top - top label for headers. If is empty, top href will be hidden. 
    {% set sections = load_wiki('file.txt', '', '') %}
    {% type, filename, _none_, text = sections[-1] %}

def uni(self, text) link | top

Function always return unicode in Python 2 or str in Python 3.

def wiki(self, doc, link='link', top='top', name='__doc__', section_level=2, system_message=False) link | top

Call some regular expressions on doc, and return it with html interpretation of wiki formating. If you want to create links to know api for your module, just call keywords function after gets full api documentation list. 
    {{ wiki(string) }}
    {{ wiki('=header1 =') }}            {# <h1>header 1</h1> #}
    {{ wiki('=header2 =') }}            {# <h2>header 2</h2> #}
    {{ wiki('=header3 =') }}            {# <h3>header 3</h3> #}
    {{ wiki('=header4 =') }}            {# <h4>header 4</h4> #}
    {{ wiki('*bold text*') }}           {# <b>bold text</b> #}
    {{ wiki('/italic text/') }}         {# <i>iatlic text</i> #}
    {{ wiki('{code text}') }}           {# <code>code text</code> #}
    {{ wiki('http://a/b') }}
Formated pre code type could be python (default if not set), jinja, ini or text. Text type stops highlighting. Code type must be on first line with hashbang prefix like in example: 
    #!python
    # simple python example
    from poorwsgi import *

    @app.route('/')                         # uri /
    def root(req):
        return 'Hello world %s' % 1234      # return text
Looks that: 
    # simple python example
    from poorwsgi import *

    @app.route('/')                         # uri /
    def root(req):
        return 'Hello world %s' % 1234      # return text
Parameters padding: 
    This is some text, which could be little bit long. Never mind
    if text is on next line.
        parameter - some text for parameter
        parameter - some text for parameter
Looks that:

This is some text, which could be little bit long. Never mind if text is on next line.
parameter - some text for parameter
parameter - some text for parameter

module context link | top

Library use context object
Module dependences: jinja2.environment , jinja2.loaders , jinja24doc.apidoc , jinja24doc.rst , jinja24doc.wiki , path , posix

class Context link | top

Class based on ApiDoc.

def generate(self, template, **kwargs) link | top

Generate html output from template.

def keywords(self, api, api_url='', types=('module', 'class', 'method', 'staticmethod', 'descriptor', 'property', 'variable', 'function', 'h1', 'h2', 'h3')) link | top

Fill internal api_url variable from names of modules, classes, functions, methods, variables or h1, h2 and h3 sections. With this, wiki can create links to this functions or classes. 
    {% set api = load_module('module') %}

    {# create api rexex for from module where api will be on
       module_api.html #}
    {% do keywords(api, 'module_api.html') %}

    {# create api rexex from module where api will be on same page #}
    {% do keywords(api) %}

    {# another way how to call keywords function without do keyword #}
    {{ keywords(api) }}    {# keywords function return empty string #}
Nice to have: there could be nice, if will be arguments in title, so mouseover event show some little detail of functions, methods or variables.

def linked_api(self, doc) link | top

Append link to api to html.

Function is called by Context.wiki or Context.rst.

def load_module(self, module) link | top

Get documentation of function, variables and classes from module.

Example: 
    {% set api = load_module('module') %}
    {% for type, name, args, doc = api[0] %}
        ...

def load_rst(self, rstfile, link='link', top='top', system_message=False) link | top

Load reStructuredText file and create docs list of headers and text.

Parameters:
rstfile - string, reStructured source file name (readme.rst)
link - link label for headers. If is empty, link href will be
hidden.
top - top label for headers. If is empty, top href will be hidden. 
    {% set sections = load_rst('readme.rst', '', '') %}
    {% type, filename, _none_, text = sections[-1] %}

def load_source(self, srcfile, code='python') link | top

Load source and format them as code 
    {{ load_source('example.py') }}
    {{ load_source('example.ini', 'ini') }}

def load_text(self, textfile) link | top

Deprecated alias for Wiki.load_wiki.

def load_wiki(self, textfile, link='link', top='top') link | top

Load file and create docs list of headers and texts.
textfile - string, text file name (manual.txt)
link - link label for headers. If is empty, link href will be
hidden.
top - top label for headers. If is empty, top href will be hidden. 
    {% set sections = load_wiki('file.txt', '', '') %}
    {% type, filename, _none_, text = sections[-1] %}

def prepare_environment(self) link | top

Prepare jinja2 environment.

This method is called internal by Context.generate method, and append Conetxt methods to jinja2 template globals. So Context.load_module, Context.keywords, local_name, property_info, wiki, Context.load_wiki, Context.load_text, Context.load_source, Context.rst, Context.load_rst and log methods and functions are enabled to call in templates.

def rst(self, doc, link='link', top='top', title='__doc__', section_level=2, system_message=False) link | top

Call reStructuredText docutil parser for doc and return it with html representation of reStructuredText formating. For more details see http://docutils.sourceforge.net/rst.html.

def uni(self, text) link | top

Function always return unicode in Python 2 or str in Python 3.

def wiki(self, doc, link='link', top='top', name='__doc__', section_level=2, system_message=False) link | top

Call some regular expressions on doc, and return it with html interpretation of wiki formating. If you want to create links to know api for your module, just call keywords function after gets full api documentation list. 
    {{ wiki(string) }}
    {{ wiki('=header1 =') }}            {# <h1>header 1</h1> #}
    {{ wiki('=header2 =') }}            {# <h2>header 2</h2> #}
    {{ wiki('=header3 =') }}            {# <h3>header 3</h3> #}
    {{ wiki('=header4 =') }}            {# <h4>header 4</h4> #}
    {{ wiki('*bold text*') }}           {# <b>bold text</b> #}
    {{ wiki('/italic text/') }}         {# <i>iatlic text</i> #}
    {{ wiki('{code text}') }}           {# <code>code text</code> #}
    {{ wiki('http://a/b') }}
Formated pre code type could be python (default if not set), jinja, ini or text. Text type stops highlighting. Code type must be on first line with hashbang prefix like in example: 
    #!python
    # simple python example
    from poorwsgi import *

    @app.route('/')                         # uri /
    def root(req):
        return 'Hello world %s' % 1234      # return text
Looks that: 
    # simple python example
    from poorwsgi import *

    @app.route('/')                         # uri /
    def root(req):
        return 'Hello world %s' % 1234      # return text
Parameters padding: 
    This is some text, which could be little bit long. Never mind
    if text is on next line.
        parameter - some text for parameter
        parameter - some text for parameter
Looks that:

This is some text, which could be little bit long. Never mind if text is on next line.
parameter - some text for parameter
parameter - some text for parameter

def log(message) link | top

Write message to stderr. 
    {% do log('some debug message') %}

module frontend link | top

Frontend command functions.

Module containts some funtcions which are run by command tools.
Module dependences: argparse , jinja24doc.context , path , posix , traceback

def auto_cmdline(description='', formater='rst', file_types=['.txt']) link | top

Function called by rst24doc and wiki24doc command tools.

def build_parser(description) link | top

Create ArgumentParser instance with all suported options.

def embed_stylesheet(args) link | top

Return stylesheets content readed from stylesheets.

def jinja_cmdline(description='') link | top

Function called by jinja24doc command tool.

def process(ctx, source, file_types, **kwargs) link | top

Run Context.generate on right internal template dependend on file_types.

def verbose(args, parser) link | top

Print info message to stderr when verbose option is set.
Create by Ondřej Tůma (McBig). © 2013. Generate by Jinja24doc.