Package epydoc :: Package docwriter :: Module xlink

Module xlink

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.

Index file

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.

Allowed names

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.

Configuration

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: 1719

Author: Daniele Varrazzo

Classes

[hide private]

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.

Functions

[hide private]

API register

register_api(name, generator=None)
Register the API name into the api\_register. source code

set_api_file(name, file)
Set an URL generator populated with data from file. source code

set_api_root(name, prefix)
Set the root for the URLs returned by a registered URL generator.

source code

create_api_role(name, problematic)
Create and register a new role to create links for an API documentation.

source code

Command line parsing

split_name(value)
Split an option in form NAME:VALUE and check if NAME exists. source code

Variables

[hide private]

API register

api_register = {}
Mapping from the API name to the UrlGenerator to be used.

_TARGET_RE = re.compile(r'^(.*?)\s*<(?:URI:|L:)?([^<>]+)>$')

Function Details

[hide private]

register_api(name, generator=None)

source code

A registered API will be available to the markup as the interpreted text role name.

If a generator is not provided, register a VoidUrlGenerator instance: in this case no warning will be issued for missing names, but no URL will be generated and all the dotted names will simply be rendered as literals.

Parameters:

name (str) - the name of the generator to be registered
generator (UrlGenerator) - the object to register to translate names into URLs.

set_api_file(name, file)

source code

Set an URL generator populated with data from file.

Use file to populate a new DocUrlGenerator instance and register it as name.

Parameters:

name (str) - the name of the generator to be registered
file (str or file) - the file to parse populate the URL generator

set_api_root(name, prefix)

source code

Set the root for the URLs returned by a registered URL generator.

Parameters:

name (str) - the name of the generator to be updated
prefix (str) - the prefix for the generated URL's

Raises:

IndexError - name is not a registered generator

create_api_role(name, problematic)

source code

Create and register a new role to create links for an API documentation.

Create a role called name, which will use the URL resolver registered as name in api\_register to create a link for an object.

Parameters:

name (str) - name of the role to create.
problematic (bool) - if True, the registered role will create problematic nodes in case of failed references. If False, a warning will be raised anyway, but the output will appear as an ordinary literal.

Variables Details

[hide private]

api_register

Mapping from the API name to the UrlGenerator to be used.

Use register\_api() to add new generators to the register.

Value:

{}