===== Endo ===== A traits-aware documentation tool. :Author: David Baer :Contact: dbaer@14853.net :Organization: `Enthought, Inc.`_ :Copyright: Copyright (C) 2005 by `Enthought, Inc.`_ :Date: 2005-08-17 Contents ******** 1. `About this document`_ 2. `Usage`_ 3. `Customization`_ About this document ******************* This document describes how to use Endo, a traits-aware documentation tool for Python. .. License info should go here Usage ***** Command-line syntax:: | python endo.py [options] [-r [package_name=path/to/package]]* | [[module_prefix=]path/to/module.py]* | | | options: | -h, --help show this help message and exit | --debug turn on debugging messages | --verbose show detailed status messages | -s, --silent ignores all warnings | --dump-state=FILE dump parser state to file and quit | | | Input options: | Specify what you want to document | -r[NAME=]PATH, --package=[NAME=]PATH | document package located at PATH (with dotted name | NAME) | -pNAME, --package-name=NAME default package name | --rst interpret docstrings as ReStructured Text | --include-protected include protected methods/functions in documentation | | | Output options: | -dDIR, --document-dir=DIR | write documentation here | | | Customization options: | Customize the generated documentation | --css=FILE add CSS stylesheet | --override-templates=DIR check this directory first for templates (revert to | default if not found) | --data=FILE additional data files to copy | --header-file=FILE file containing HTML text to use as header | --header=STRING HTML text to use as a header | --footer-file=FILE file containing HTML text to use as a footer | --footer=STRING HTML text to use as a footer Examples ^^^^^^^^ :: python endo.py --verbose --include-protected --rst \ -r /var/code/enthought/ -d /home/user/docs/enthought_api Executing the script with these options would document the package contained in the directory /var/code/enthought/, which is assumed to have the name 'enthought'. (This is equivalent to '-r enthought=/var/code/enthought/'). Endo documents all modules in this directory, as well as all subpackages in the subdirectories of /var/code/enthought. In this case, all objects, including those with leading underscores, will be documented (--include-protected). Documentation strings will be interpreted as ReStructured Text (--rst). Endo will print status messages to the screen as it processes and documents each module (--verbose). The documentation will be generated in the directory /home/user/docs/enthought_api. :: python endo.py --override-templates=/home/user/mytemplates \ --css=/home/user/stylesheet1.css \ --footer="This was generated using Endo" \ -d /home/user/docs spam.py mypackage=eggs.py In this example Endo documents spam and eggs, found in the current directory. The documentation will be generated in /home/user/docs. The module spam is treated as part of the default package, while eggs is given a package name and becomes mypackage.eggs. A number of customization features are demonstrated here. Endo will look for HTML templates in /home/user/mytemplates first, defaulting to the template set included in the distribution for any templates not present in this directory (see `Templates`_). An additional stylesheet, /home/user/stylesheet1.css, is given, whose rules will be applied *after* the default stylesheet's rules. The footer text will appear at the bottom of each generated page. Customization ************* There are a number of ways to customize Endo's output. * The --css switch allows you to specify additional stylesheets. * The --header, --footer, --header-file, and --footer-file switches allow you to include custom HTML at the top of each page. Templates ^^^^^^^^^ The most powerful feature for customizing output is the template system. Endo uses HTML templates to separate the form of the documentation from the information needed to produce it. This allows you a great deal of freedom to create different presentations of the same information. Endo's template engine uses a straightforward syntax. Tags, enclosed in ``{% %}`` or ``{{ }}``, allow you to create control structures and to bring information into the output. Everything else is copied directly into the generated HTML files. When a template is rendered, it has a *context*, a set of names and associated values. Endo is responsible for generating the context, but it is the templates that produce the HTML pages. Template tags: ``{{ EXPR }}`` Evaluate EXPR against the template context and insert the result in the output. Use Python syntax. ``{% assign VAR=EXPR %}`` Assign the name VAR in the current context to the value of EXPR. ``{% block NAME %}{% endblock %}`` Everything enclosed in a block may be overridden by an extending template. ``{% extends "base_template" %}`` Render "base_template", but replace all blocks that are overridden in this template ``{% for VAR1[,VAR2[,VAR3]] in LIST_EXPR %}{% endfor %}`` A for loop, just as in Python. ``{% if TEST %} [{% else %}] {% endif %}`` Evaluate test and execute the appropriate block. ``{% include TEMPLATE [PARAM1=EXPR1 [PARAM2=EXPR2]] %}`` Evaluate the specified template against the current context (with specified additional parameters), and insert the resulting text in the output. The basic templates are listed below. There are more specialized templates, but these are generally smaller and easier to understand. You can find the templates in the data/ subdirectory of the distribution. Template files have the suffix '.html', though the suffix is dropped in ``{% base %}`` and ``{% include %}``. +--------------+-------------------+------------------+---------------------------+ | Template | Description | Context variable | Meaning | +==============+===================+==================+===========================+ | base | Basic page layout | title | Page title (window) | | | +------------------+---------------------------+ | | | header_title | Title to show at the top | | | | | of the page | | | +------------------+---------------------------+ | | | stylesheet | Primary stylesheet | | | +------------------+---------------------------+ | | | extrastylesheets | List of stylesheets to | | | | | apply to page | | | +------------------+---------------------------+ | | | customheader, | Custom header and footer | | | | customfooter | | +--------------+-------------------+------------------+---------------------------+ | module_index | Hierarchical | docstring | Docstring to display at | | (extends | module and package| | top of index | | base) | index +------------------+---------------------------+ | | | package_hierarchy| | | | +------------------+---------------------------+ | | | module_hierarchy | | +--------------+-------------------+------------------+---------------------------+ | alpha_list | Display an | letter_list | List of first letters | | (extends | alphabetical index+------------------+---------------------------+ | base) | (class, namespace)| objects | Dictionary mapping first | | | | | letters to a list of | | | | | tuples (link, | | | | | display_name, description)| +--------------+-------------------+------------------+---------------------------+ | hierarchy, | Display | hierarchy | List of tuples (object, | | hierarchy_r | hierarchical tree | | link, subobjects), where | | (recursive) | control | | subobjects has the same | | (extends | | | | | base) | | | | | | | | format as hierarchy | +--------------+-------------------+------------------+---------------------------+ .. _`Enthought, Inc.` : http://www.enthought.com/