Package epydoc :: Package docwriter :: Module xlink

[hide private]
[frames] | no frames]

# Module xlink

source code

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

Author: Daniele Varrazzo

Copyright: Copyright (C) 2007 by 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.

Function Details | [hide private]

### register_api(name, generator=None)

source code

Register the API `name` into the api_register.

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:

      {}