Package: ulif.rest
ulif.restis a package that provides some ReStructuredText extensions. The
extensions collected in this package provide support for some of the
markup used in RestructuredText documents of the stock Python
documentation toolchain. Also a pygments directive (written by Georg
Brandl) is included, which enables syntax highlighting of code
fragments in reStructuredText docs with thepygmentspackage.SeeREADME.txtin thesrc/ulif/restdirectory for API
documentation.Note, that this is alphaware! Do not use it in productive
environments!PrerequisitesYou need:Python 2.4. Rumors are, that also Python 2.5 will do.setuptools, available fromhttp://peak.telecommunity.com/DevCenter/setuptoolsOther needed packages will be downloaded during
installation. Therefore you need an internet connection during
installation.InstallationNormally, this package should from other packages, that use it as a
helper lib. Thus, you do not have to care for installation. If you
want to integrateulif.restin your project, just declareulif.restas a required package in yoursetup.py.withbuildoutYou can install this package withbuildoutas follows:From the root of the package run:$ python2.4 bootstrap/bootstrap.pyThis will download and install everything to runbuildoutin the
next step. Afterwards an executable scriptbuildoutshould be
available in the freshly createdbin/directory.Next, fetch all needed packages, install them and create provided
scripts:$ bin/buildoutThis should create atestscript inbin/.Running:$ bin/testyou can test the installed package.witheasy_installRun as a superuser:# easy_install ulif.restThis should make the package available in your system Python.UsageSeeREADME.txtand other .txt files in thesrc/ulif/rest/directory
for API documentation.Detailed DocumentationRestructuredText (ReST) ExtensionsWhat is this?The extensions collected in this package provide support for some of
the markup used in RestructuredText documents of the stock Python
documentation toolchain.RestructuredText is a document markup language with special human
readable markup, that is widely spread in the Python
world. RestructuredText documents are a bit like HTML but better
readable. The text you are reading, for example, is written as ReST.Seehttp://docutils.sourceforge.net/rst.htmlto learn more about ReST (anddocutils).Normally, ReST documents can be processed with tools of the Python
packagedocutils. Thedocutilsinclude so-called readers,
parsers, writers and publishers for reading ReST documents and writing
various output formats like HTML, XML or LaTeX.Since Python switched from LaTeX to ReST documentation with the 2.6
version, some special markup was introduced likefunction,seealsoorversionchanged, that helps to describe a
programming API more precisely. These additional ‘tags’, however,
needed specialized readers, parsers, writers and publishers to be
understood. The normal docutils tools did not understand the new roles
and directives.This package makes it possible to use the standarddocutilsparsers and writers with the additional roles and directives listed
below.Prerequisites and requirementsdocutils– version 0.4 is recommended.It can be retrieved fromhttp://docutils.sourceforge.net/.Pygments– a syntax highlighter.It can be retrieved fromhttp://pygments.org/. This is only needed,
if you want syntax highlighting of code fragments in your ReST
documents.Because there is currently only support for HTML with pygments, you
won’t use it for other output formats. In this case you don’t need
pygments.Both packages can also retrieved via cheeseshop andeasy_install.Activate support for the additional set of roles/directivesJust import the modules in this package:from ulif.rest import directives_plain
from ulif.rest import roles_plain
from ulif.rest import pygments_directive # for syntax-highlighting supportThat’s it. The modules define and register the new roles and
directives with thedocutilsautomatically. You don’t have to call
a special function.Running the testsCalltests/alltests.pywith your favourite Python interpreter:$ python tests/alltests.pyNote, thatdocutilsmust be available in your PYTHON_PATH.If you installed the source version with buildout (not an egg), you
can generate abuildoutexecutable in the bin/ directory of the
source root and run:$ bin/testWhich roles and directives are supported:pygments_directiveadds the following new directives:sourcecode– a directive to highlight syntax of the followingcode block. It takes one parameter, the language,
and currently only supports HTML output.Example:.. sourcecode:: python

   class Cave(object):
        pass

This will render the class definition with
colours.

An additional optional parameter is ``linenos``,
which adds linenumbers to the code::

.. sourcecode:: python
   :linenos:

   class NumberedCave(object):
       pass

will render the code block with line numbering.

See the source for further options.code-block– an alias forsourcecode.directives_plainadds the follwing new directives:function– a directive to describe functions with theirsignature.data– ???class– a directive to define a Python class.method– a directive to describe the method of a Python class.attribute– a directive to describe an attribute of a Pythonclass.exception– a directive to describe an exception.cmdoption– a directive to describe a command option.envvar– a directive to describe an environment variable.describe– a directive to describe something.seealso– a directive to add a ‘See also’ subsection. It requiressome ‘body’-text.deprecated– a directive to add a deprecation warning. It alsorequires some explanatory body text and a version
number.versionadded– a directive to add a note that tells, in whichversion the surrounding thing was added to the
API.Requires a version number and an explanatory text.Example:.. versionadded:: 0.11

   Added for convenience reasons.versionchanged– a directive to add a note that tell, in whichversion a signature or something else changed
and why.Example:.. versionchanged:: 0.11

  Added cave parameter, because every caveman
  needs a cave.toctree– a directive that requests to generate atable-of-contents tree of files, given in the body part
of the directive. The so-called toc-tree will not
be generated by standard writers, because it needs at
least two parsing passes (one to collect all
references, another pass to generate the reference
targets).If you insert a toctree directive in a document, this
will not block parsing of the document any more, but
the toctree will be ‘invisible’ in rendered documents.The toctree directive supports amaxdepthparameter, a number, that tells, to which depth a
toctree should be generated (default: no limit).Example:.. toctree::
   :maxdepth: 2

   chapter1.rst
   chapter2.rst
   another_file.rst

This should render a table of contents with the
headings of the three given files. Only headers of
level 1 and 2 will be included in the toctree.roles_plainadds the following new roles:dataexcfuncclassconstattrmethcfunccdatactypecmacromodkeywordreftokentermfilesampEvery role can be used like this :<rolename>:<text>. For example::func:`my_function`will output the textmy_function, rendered in
a different way than normal text. The exact kind of rendering depends
on the writer and translator that is used. In usual HTML writers it
will be rendered with roman fonts.The same applies to all the other roles.CHANGES0.1.0 (2008-02-24)Feature changesInitial ReleaseDownload