Home | Trees | Indices | Help |
|
---|
|
A Docutils interpreted text role for cross-API reference support.
This module allows a Docutils document to refer to elements defined in external API documentation. It is possible to refer to many external API from the same document.
Each API documentation is assigned a new interpreted text role: using such interpreted text, an user can specify an object name inside an API documentation. The system will convert such text into an url and generate a reference to it. For example, if the API db is defined, being a database package, then a certain method may be referred as:
:db:`Connection.cursor()`
To define a new API, an index file must be provided. This file contains a mapping from the object name to the URL part required to resolve such object.
Each line in the the index file describes an object.
Each line contains the fully qualified name of the object and the URL at which the documentation is located. The fields are separated by a <tab> character.
The URL's in the file are relative from the documentation root: the system can be configured to add a prefix in front of each returned URL.
When a name is used in an API text role, it is split over any separator. The separators defined are '.', '::', '->'. All the text from the first noise char (neither a separator nor alphanumeric or '_') is discarded. The same algorithm is applied when the index file is read.
First the sequence of name parts is looked for in the provided index file. If no matching name is found, a partial match against the trailing part of the names in the index is performed. If no object is found, or if the trailing part of the name may refer to many objects, a warning is issued and no reference is created.
This module provides the class ApiLinkReader a replacement for the Docutils standalone reader. Such reader specifies the settings required for the API canonical roles configuration. The same command line options are exposed by Epydoc.
The script apirst2html.py is a frontend for the ApiLinkReader reader.
API Linking Options:
--external-api=NAME Define a new API document. A new interpreted text role NAME will be added. --external-api-file=NAME:FILENAME Use records in FILENAME to resolve objects in the API named NAME. --external-api-root=NAME:STRING Use STRING as prefix for the URL generated from the API NAME.
Version: 1556
Author: Daniele Varrazzo
Copyright: Copyright (C) 2007 by Daniele Varrazzo
|
|||
UrlGenerator Generate URL from an object name. |
|||
VoidUrlGenerator Don't actually know any url, but don't report any error. |
|||
DocUrlGenerator Read a documentation index and generate URL's for it. |
|||
Command line parsing | |||
---|---|---|---|
ApiLinkReader A Docutils standalone reader allowing external documentation links. |
|
|||
API register | |||
---|---|---|---|
|
|||
|
|||
|
|||
|
|||
Command line parsing | |||
|
|
|||
API register | |||
---|---|---|---|
api_register =
Mapping from the API name to the UrlGenerator to be used. |
|
Register the API A registered API is available to the markup as the interpreted text role name. If a
|
Set an URL generator populated with data from Use
|
|
Create and register a new role to create links for an API documentation. Create a role called |
Home | Trees | Indices | Help |
|
---|
Generated by Epydoc 3.0beta1 on Thu Mar 1 04:23:14 2007 | http://epydoc.sourceforge.net |