logo

Jinja24Doc for Python

Lightweight documentation generator with jinja2 templates.

Basic usage

Public templates

Data structure

Writing documentation

Module context

def log

The main power of Jinja2doc environment is Jinja2 templates which is use for formating documentation output. First, Jinja2doc was be create for python modules documentation.

Basic usagelink | top

There are few function, which is available in jinja2 templates. First two load_module, load_rst and load_wiki returns documentation list. Function load_wiki is deprecated alias for load_wiki.

{% set api = load_module('module') %}
{% set rst_sections = load_rst('file.rst') %}
{% set wiki_sections = load_wiki('file.wiki') %}

Other functions works with string, they format it. Function rst generate html string formated with base rst syntax, wiki for wiki formated text. It know headers, bold text, parameter padding, code block or paragraphs defined with double newline. Both of these functions could create PEP and RFC links to api definition. If you want to create api links, you must fill api regex variable by keywords function first.

{% do keywords(api, 'api_page.html') %}
{{ wiki(api[0][3]) }}   {# put to document formated first documentation #}
                        {# from api (it wold be module documentation #}

Keywords function returns empty string, so you can call it from {{ }} block. Next, keywords rewrite internal variables api regex and api link, so in this moment, there cant do api linking for more than one page. If you have more than one module on one page, you can join api variable from both of them.

{% set api = load_module('first_module') %}
{% set api = api + load_module('second_module') %}
{% do keywords(api, 'api_page.html') %}
{{ wiki(api[0][3]) }}

Public templateslink | top

There are some public templates, which you can find in share/jinja24doc/templates directory.

module.html

This template is use by rst24doc and wiki24doc command tools to generate documentation from python module by one command.

text.html

Like module.html, but for generate documentation from text source file.

_simple.html

Simple html web page. Style is included.

_simple_with_submodules.html

Simple html web page. Style is included. All submodules are included recursive. This could be demo, how you can generate manual from your code recursively.

_reference.html

This template generates html pages looks like Jinja24Doc manual. There are some different styles:red.css, blue.css, green.css, gray.css and inverse.css which you can use with this template. You must only copy to output directory as style.css ;) _reference.html template is used in module.html

_text.html

This template looks like _reference.html, but it is prepare to generate html page from text. This template needs sections instead of api variable, which looks contain data generate from text file. See to Context.load_rst or Context.load_wiki functions.

Like reference.html template, this use styles too, so You must only copy to output directory as style.css too.

Data structurelink | top

The documentation list which returns functions load_module, load_rst and load_wiki looks like that:

((type, name, args, documentation),)    # all values are strings

Of course, some items don't have all values, so on their place is None or another value, typical for their type. Modules could have author, date and version, if it available. Submodules, do not have documentation. Dependences are modules, which is not import, but there is import some routines from that. And variables jave value instead of arguments. If you want to doing documentation for it, that is comment on one line before. Next list is typical for load_module function.

(('module', 'name', ('author', 'date', 'version'), 'documentation'),
 ('submodule', 'name', None, ''),
 ('dependence', 'name', None, ''),
 ('class', 'ClassName', None, 'documentation'),
 ('property', 'ClassName.name', (READ, WRITE, DELETE), 'documentation')),
 ('descriptor', 'ClassName.name', args, 'documentation')),
 ('method', 'ClassName.name', args, 'documentation')),
 ('staticmethod', 'ClassName.name', args, 'documentation')),
 ('function', 'name', args, 'documentation'),
 ('variable', 'name', value, 'documentation'))

For load_rst and load_wiki function is this typical list:

(('h1', 'title', None, ''),     # = title =
 ('h2', 'title', None, ''),     # == title ==
 ('h3', 'title', None, ''),     # === title ===
 ('h4', 'title', None, ''),     # ==== title ====
 ('text', '', None, 'text to end or next header'))

Writing documentationlink | top

The best way, is write documentation in PEP 257. Documentation which is gets from pytnon elements is read with inspect.getdoc function. This function reads element.__doc__ variable, so this variable is fill by creating comment in element definition.

Problem could be variables. Jinja24Doc (and python documentation system) cant set documentation for variable. But some documentation system, and jinja2doc too have some special mechanisms how to get variable documentation. Jinja24Doc looks for previous line of first variable definition. So you can create one-line documentation make by comments.

# this is comment ehmm documentation for this nice new instance
foo = Foo()

# this is not documentation for foo, because this is second definition of
# it
foo = Goo()

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

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') %}