"""
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.
.. _Docutils: http://docutils.sourceforge.net/
"""
# $Id: xlink.py 1586 2007-03-14 01:53:42Z dvarrazzo $
__version__ = "$Revision: 1586 $"[11:-2]
__author__ = "Daniele Varrazzo"
__copyright__ = "Copyright (C) 2007 by Daniele Varrazzo"
__docformat__ = 'reStructuredText en'
import re
import sys
from optparse import OptionValueError
from epydoc import log
class UrlGenerator:
"""
Generate URL from an object name.
"""
class IndexAmbiguous(IndexError):
"""
The name looked for is ambiguous
"""
def get_url(self, name):
"""Look for a name and return the matching URL documentation.
First look for a fully qualified name. If not found, try with partial
name.
If no url exists for the given object, return `None`.
:Parameters:
`name` : `str`
the name to look for
:return: the URL that can be used to reach the `name` documentation.
`None` if no such URL exists.
:rtype: `str`
:Exceptions:
- `IndexError`: no object found with `name`
- `DocUrlGenerator.IndexAmbiguous` : more than one object found with
a non-fully qualified name; notice that this is an ``IndexError``
subclass
"""
raise NotImplementedError
def get_canonical_name(self, name):
"""
Convert an object name into a canonical name.
the canonical name of an object is a tuple of strings containing its
name fragments, splitted on any allowed separator ('``.``', '``::``',
'``->``').
Noise such parenthesis to indicate a function is discarded.
:Parameters:
`name` : `str`
an object name, such as ``os.path.prefix()`` or ``lib::foo::bar``
:return: the fully qualified name such ``('os', 'path', 'prefix')`` and
``('lib', 'foo', 'bar')``
:rtype: `tuple` of `str`
"""
rv = []
for m in self._SEP_RE.finditer(name):
groups = m.groups()
if groups[0] is not None:
rv.append(groups[0])
elif groups[2] is not None:
break
return tuple(rv)
_SEP_RE = re.compile(r"""(?x)
# Tokenize the input into keyword, separator, noise
([a-zA-Z0-9_]+) | # A keyword is a alphanum word
( \. | \:\: | \-\> ) | # These are the allowed separators
(.) # If it doesn't fit, it's noise.
# Matching a single noise char is enough, because it
# is used to break the tokenization as soon as some noise
# is found.
""")
class VoidUrlGenerator(UrlGenerator):
"""
Don't actually know any url, but don't report any error.
Useful if an index file is not available, but a document linking to it
is to be generated, and warnings are to be avoided.
Don't report any object as missing, Don't return any url anyway.
"""
def get_url(self, name):
return None
class DocUrlGenerator(UrlGenerator):
"""
Read a *documentation index* and generate URL's for it.
"""
def __init__(self):
self._exact_matches = {}
"""
A map from an object fully qualified name to its URL.
Values are both the name as tuple of fragments and as read from the
records (see `load_records()`), mostly to help `_partial_names` to
perform lookup for unambiguous names.
"""
self._partial_names= {}
"""
A map from partial names to the fully qualified names they may refer.
The keys are the possible left sub-tuples of fully qualified names,
the values are list of strings as provided by the index.
If the list for a given tuple contains a single item, the partial
match is not ambuguous. In this case the string can be looked up in
`_exact_matches`.
If the name fragment is ambiguous, a warning may be issued to the user.
The items can be used to provide an informative message to the user,
to help him qualifying the name in a unambiguous manner.
"""
self.prefix = ''
"""
Prefix portion for the URL's returned by `get_url()`.
"""
self._filename = None
"""
Not very important: only for logging.
"""
def get_url(self, name):
cname = self.get_canonical_name(name)
url = self._exact_matches.get(cname, None)
if url is None:
# go for a partial match
vals = self._partial_names.get(cname)
if vals is None:
raise IndexError(
"no object named '%s' found" % (name))
elif len(vals) == 1:
url = self._exact_matches[vals[0]]
else:
raise self.IndexAmbiguous(
"found %d objects that '%s' may refer to: %s"
% (len(vals), name, ", ".join(["'%s'" % n for n in vals])))
return self.prefix + url
#{ Content loading
# ---------------
def clear(self):
"""
Clear the current class content.
"""
self._exact_matches.clear()
self._partial_names.clear()
def load_index(self, f):
"""
Read the content of an index file.
Populate the internal maps with the file content using `load_records()`.
:Parameters:
f : `str` or file
a file name or file-like object fron which read the index.
"""
self._filename = str(f)
if isinstance(f, basestring):
f = open(f)
self.load_records(self._iter_tuples(f))
def _iter_tuples(self, f):
"""Iterate on a file returning 2-tuples."""
for nrow, row in enumerate(f):
# skip blank lines
row = row.rstrip()
if not row: continue
rec = row.split('\t', 2)
if len(rec) == 2:
yield rec
else:
log.warning("invalid row in '%s' row %d: '%s'"
% (self._filename, nrow+1, row))
def load_records(self, records):
"""
Read a sequence of pairs name -> url and populate the internal maps.
:Parameters:
records : iterable
the sequence of pairs (*name*, *url*) to add to the maps.
"""
for name, url in records:
cname = self.get_canonical_name(name)
if not cname:
log.warning("invalid object name in '%s': '%s'"
% (self._filename, name))
continue
# discard duplicates
if name in self._exact_matches:
continue
self._exact_matches[name] = url
self._exact_matches[cname] = url
# Link the different ambiguous fragments to the url
for i in range(1, len(cname)):
self._partial_names.setdefault(cname[i:], []).append(name)
#{ API register
# ------------
api_register = {}
"""
Mapping from the API name to the `UrlGenerator` to be used.
Use `register_api()` to add new generators to the register.
"""
def register_api(name, generator=None):
"""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.
"""
if generator is None:
generator = VoidUrlGenerator()
api_register[name] = generator
def set_api_file(name, file):
"""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
"""
generator = DocUrlGenerator()
generator.load_index(file)
register_api(name, generator)
def set_api_root(name, prefix):
"""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
:Exceptions:
- `IndexError`: `name` is not a registered generator
"""
api_register[name].prefix = prefix
######################################################################
# Below this point requires docutils.
try:
import docutils
from docutils.parsers.rst import roles
from docutils import nodes,utils
from docutils.readers.standalone import Reader
except ImportError:
docutils = roles = nodes = utils = None
class Reader: settings_spec = ()
def create_api_role(name, problematic):
"""
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.
"""
def resolve_api_name(n, rawtext, text, lineno, inliner,
options={}, content=[]):
if docutils is None:
raise AssertionError('requires docutils')
# node in monotype font
text = utils.unescape(text)
node = nodes.literal(rawtext, text, **options)
# Get the resolver from the register and create an url from it.
try:
url = api_register[name].get_url(text)
except IndexError, exc:
msg = inliner.reporter.warning(str(exc), line=lineno)
if problematic:
prb = inliner.problematic(rawtext, text, msg)
return [prb], [msg]
else:
return [node], []
if url is not None:
node = nodes.reference(rawtext, '', node, refuri=url, **options)
return [node], []
roles.register_local_role(name, resolve_api_name)
#{ Command line parsing
# --------------------
def split_name(value):
"""
Split an option in form ``NAME:VALUE`` and check if ``NAME`` exists.
"""
parts = value.split(':', 1)
if len(parts) != 2:
raise OptionValueError(
"option value must be specified as NAME:VALUE; got '%s' instead"
% value)
name, val = parts
if name not in api_register:
raise OptionValueError(
"the name '%s' has not been registered; use --external-api"
% name)
return (name, val)
class ApiLinkReader(Reader):
"""
A Docutils standalone reader allowing external documentation links.
The reader configure the url resolvers at the time `read()` is invoked the
first time.
"""
#: The option parser configuration.
settings_spec = (
'API Linking Options',
None,
((
'Define a new API document. A new interpreted text role NAME will be '
'added.',
['--external-api'],
{'metavar': 'NAME', 'action': 'append'}
), (
'Use records in FILENAME to resolve objects in the API named NAME.',
['--external-api-file'],
{'metavar': 'NAME:FILENAME', 'action': 'append'}
), (
'Use STRING as prefix for the URL generated from the API NAME.',
['--external-api-root'],
{'metavar': 'NAME:STRING', 'action': 'append'}
),)) + Reader.settings_spec
def __init__(self, *args, **kwargs):
if docutils is None:
raise AssertionError('requires docutils')
Reader.__init__(self, *args, **kwargs)
def read(self, source, parser, settings):
self.read_configuration(settings, problematic=True)
return Reader.read(self, source, parser, settings)
def read_configuration(self, settings, problematic=True):
"""
Read the configuration for the configured URL resolver.
Register a new role for each configured API.
:Parameters:
`settings`
the settings structure containing the options to read.
`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.
"""
# Read config only once
if hasattr(self, '_conf'):
return
ApiLinkReader._conf = True
try:
if settings.external_api is not None:
for name in settings.external_api:
register_api(name)
create_api_role(name, problematic=problematic)
if settings.external_api_file is not None:
for name, file in map(split_name, settings.external_api_file):
set_api_file(name, file)
if settings.external_api_root is not None:
for name, root in map(split_name, settings.external_api_root):
set_api_root(name, root)
except OptionValueError, exc:
print >>sys.stderr, "%s: %s" % (exc.__class__.__name__, exc)
sys.exit(2)
read_configuration = classmethod(read_configuration)
|