commit
a98c9eaac3
14 changed files with 7262 additions and 0 deletions
@ -0,0 +1,262 @@
|
||||
# $Id: __init__.py 8147 2017-08-03 09:01:16Z grubert $ |
||||
# Author: David Goodger <goodger@python.org> |
||||
# Copyright: This module has been placed in the public domain. |
||||
|
||||
""" |
||||
This is the Docutils (Python Documentation Utilities) package. |
||||
|
||||
Package Structure |
||||
================= |
||||
|
||||
Modules: |
||||
|
||||
- __init__.py: Contains component base classes, exception classes, and |
||||
Docutils version information. |
||||
|
||||
- core.py: Contains the ``Publisher`` class and ``publish_*()`` convenience |
||||
functions. |
||||
|
||||
- frontend.py: Runtime settings (command-line interface, configuration files) |
||||
processing, for Docutils front-ends. |
||||
|
||||
- io.py: Provides a uniform API for low-level input and output. |
||||
|
||||
- nodes.py: Docutils document tree (doctree) node class library. |
||||
|
||||
- statemachine.py: A finite state machine specialized for |
||||
regular-expression-based text filters. |
||||
|
||||
Subpackages: |
||||
|
||||
- languages: Language-specific mappings of terms. |
||||
|
||||
- parsers: Syntax-specific input parser modules or packages. |
||||
|
||||
- readers: Context-specific input handlers which understand the data |
||||
source and manage a parser. |
||||
|
||||
- transforms: Modules used by readers and writers to modify DPS |
||||
doctrees. |
||||
|
||||
- utils: Contains the ``Reporter`` system warning class and miscellaneous |
||||
utilities used by readers, writers, and transforms. |
||||
|
||||
utils/urischemes.py: Contains a complete mapping of known URI addressing |
||||
scheme names to descriptions. |
||||
|
||||
- utils/math: Contains functions for conversion of mathematical notation |
||||
between different formats (LaTeX, MathML, text, ...). |
||||
|
||||
- writers: Format-specific output translators. |
||||
""" |
||||
|
||||
import sys |
||||
|
||||
|
||||
__docformat__ = 'reStructuredText' |
||||
|
||||
__version__ = '0.14' |
||||
"""Docutils version identifier (complies with PEP 440):: |
||||
|
||||
major.minor[.micro][releaselevel[serial]][.dev] |
||||
|
||||
* The major number will be bumped when the project is feature-complete, and |
||||
later if there is a major change in the design or API. |
||||
* The minor number is bumped whenever there are new features. |
||||
* The micro number is bumped for bug-fix releases. Omitted if micro=0. |
||||
* The releaselevel identifier is used for pre-releases, one of 'a' (alpha), |
||||
'b' (beta), or 'rc' (release candidate). Omitted for final releases. |
||||
* The serial release number identifies prereleases; omitted if 0. |
||||
* The '.dev' suffix indicates active development, not a release, before the |
||||
version indicated. |
||||
|
||||
For version comparison operations, use `__version_info__` |
||||
rather than parsing the text of `__version__`. |
||||
""" |
||||
|
||||
# workaround for Python < 2.6: |
||||
__version_info__ = (0, 14, 0, 'final', 0, True) |
||||
# To add in Docutils 0.15, replacing the line above: |
||||
""" |
||||
from collections import namedtuple |
||||
VersionInfo = namedtuple( |
||||
'VersionInfo', 'major minor micro releaselevel serial release') |
||||
__version_info__ = VersionInfo( |
||||
major=0, |
||||
minor=15, |
||||
micro=0, |
||||
releaselevel='alpha', # development status: |
||||
# one of 'alpha', 'beta', 'candidate', 'final' |
||||
serial=0, # pre-release number (0 for final releases) |
||||
release=False # True for official releases and pre-releases |
||||
) |
||||
|
||||
Comprehensive version information tuple. Can be used to test for a |
||||
minimally required version, e.g. :: |
||||
|
||||
if __version_info__ >= (0, 13, 0, 'candidate', 2, True) |
||||
|
||||
or in a self-documenting way like :: |
||||
|
||||
if __version_info__ >= docutils.VersionInfo( |
||||
major=0, minor=13, micro=0, |
||||
releaselevel='candidate', serial=2, release=True) |
||||
""" |
||||
|
||||
__version_details__ = '' |
||||
"""Optional extra version details (e.g. 'snapshot 2005-05-29, r3410'). |
||||
(For development and release status see `__version_info__`.) |
||||
""" |
||||
|
||||
|
||||
class ApplicationError(StandardError): |
||||
# Workaround: |
||||
# In Python < 2.6, unicode(<exception instance>) calls `str` on the |
||||
# arg and therefore, e.g., unicode(StandardError(u'\u234')) fails |
||||
# with UnicodeDecodeError. |
||||
if sys.version_info < (2,6): |
||||
def __unicode__(self): |
||||
return u', '.join(self.args) |
||||
|
||||
|
||||
class DataError(ApplicationError): pass |
||||
|
||||
|
||||
class SettingsSpec: |
||||
|
||||
""" |
||||
Runtime setting specification base class. |
||||
|
||||
SettingsSpec subclass objects used by `docutils.frontend.OptionParser`. |
||||
""" |
||||
|
||||
settings_spec = () |
||||
"""Runtime settings specification. Override in subclasses. |
||||
|
||||
Defines runtime settings and associated command-line options, as used by |
||||
`docutils.frontend.OptionParser`. This is a tuple of: |
||||
|
||||
- Option group title (string or `None` which implies no group, just a list |
||||
of single options). |
||||
|
||||
- Description (string or `None`). |
||||
|
||||
- A sequence of option tuples. Each consists of: |
||||
|
||||
- Help text (string) |
||||
|
||||
- List of option strings (e.g. ``['-Q', '--quux']``). |
||||
|
||||
- Dictionary of keyword arguments sent to the OptionParser/OptionGroup |
||||
``add_option`` method. |
||||
|
||||
Runtime setting names are derived implicitly from long option names |
||||
('--a-setting' becomes ``settings.a_setting``) or explicitly from the |
||||
'dest' keyword argument. |
||||
|
||||
Most settings will also have a 'validator' keyword & function. The |
||||
validator function validates setting values (from configuration files |
||||
and command-line option arguments) and converts them to appropriate |
||||
types. For example, the ``docutils.frontend.validate_boolean`` |
||||
function, **required by all boolean settings**, converts true values |
||||
('1', 'on', 'yes', and 'true') to 1 and false values ('0', 'off', |
||||
'no', 'false', and '') to 0. Validators need only be set once per |
||||
setting. See the `docutils.frontend.validate_*` functions. |
||||
|
||||
See the optparse docs for more details. |
||||
|
||||
- More triples of group title, description, options, as many times as |
||||
needed. Thus, `settings_spec` tuples can be simply concatenated. |
||||
""" |
||||
|
||||
settings_defaults = None |
||||
"""A dictionary of defaults for settings not in `settings_spec` (internal |
||||
settings, intended to be inaccessible by command-line and config file). |
||||
Override in subclasses.""" |
||||
|
||||
settings_default_overrides = None |
||||
"""A dictionary of auxiliary defaults, to override defaults for settings |
||||
defined in other components. Override in subclasses.""" |
||||
|
||||
relative_path_settings = () |
||||
"""Settings containing filesystem paths. Override in subclasses. |
||||
Settings listed here are to be interpreted relative to the current working |
||||
directory.""" |
||||
|
||||
config_section = None |
||||
"""The name of the config file section specific to this component |
||||
(lowercase, no brackets). Override in subclasses.""" |
||||
|
||||
config_section_dependencies = None |
||||
"""A list of names of config file sections that are to be applied before |
||||
`config_section`, in order (from general to specific). In other words, |
||||
the settings in `config_section` are to be overlaid on top of the settings |
||||
from these sections. The "general" section is assumed implicitly. |
||||
Override in subclasses.""" |
||||
|
||||
|
||||
class TransformSpec: |
||||
|
||||
""" |
||||
Runtime transform specification base class. |
||||
|
||||
TransformSpec subclass objects used by `docutils.transforms.Transformer`. |
||||
""" |
||||
|
||||
def get_transforms(self): |
||||
"""Transforms required by this class. Override in subclasses.""" |
||||
if self.default_transforms != (): |
||||
import warnings |
||||
warnings.warn('default_transforms attribute deprecated.\n' |
||||
'Use get_transforms() method instead.', |
||||
DeprecationWarning) |
||||
return list(self.default_transforms) |
||||
return [] |
||||
|
||||
# Deprecated; for compatibility. |
||||
default_transforms = () |
||||
|
||||
unknown_reference_resolvers = () |
||||
"""List of functions to try to resolve unknown references. Unknown |
||||
references have a 'refname' attribute which doesn't correspond to any |
||||
target in the document. Called when the transforms in |
||||
`docutils.tranforms.references` are unable to find a correct target. The |
||||
list should contain functions which will try to resolve unknown |
||||
references, with the following signature:: |
||||
|
||||
def reference_resolver(node): |
||||
'''Returns boolean: true if resolved, false if not.''' |
||||
|
||||
If the function is able to resolve the reference, it should also remove |
||||
the 'refname' attribute and mark the node as resolved:: |
||||
|
||||
del node['refname'] |
||||
node.resolved = 1 |
||||
|
||||
Each function must have a "priority" attribute which will affect the order |
||||
the unknown_reference_resolvers are run:: |
||||
|
||||
reference_resolver.priority = 100 |
||||
|
||||
Override in subclasses.""" |
||||
|
||||
|
||||
class Component(SettingsSpec, TransformSpec): |
||||
|
||||
"""Base class for Docutils components.""" |
||||
|
||||
component_type = None |
||||
"""Name of the component type ('reader', 'parser', 'writer'). Override in |
||||
subclasses.""" |
||||
|
||||
supported = () |
||||
"""Names for this component. Override in subclasses.""" |
||||
|
||||
def supports(self, format): |
||||
""" |
||||
Is `format` supported by this component? |
||||
|
||||
To be used by transforms to ask the dependent component if it supports |
||||
a certain input context or output format. |
||||
""" |
||||
return format in self.supported |
||||
@ -0,0 +1,172 @@
|
||||
# $Id: __init__.py 6433 2010-09-28 08:21:25Z milde $ |
||||
# Authors: David Goodger <goodger@python.org>; Ueli Schlaepfer |
||||
# Copyright: This module has been placed in the public domain. |
||||
|
||||
""" |
||||
This package contains modules for standard tree transforms available |
||||
to Docutils components. Tree transforms serve a variety of purposes: |
||||
|
||||
- To tie up certain syntax-specific "loose ends" that remain after the |
||||
initial parsing of the input plaintext. These transforms are used to |
||||
supplement a limited syntax. |
||||
|
||||
- To automate the internal linking of the document tree (hyperlink |
||||
references, footnote references, etc.). |
||||
|
||||
- To extract useful information from the document tree. These |
||||
transforms may be used to construct (for example) indexes and tables |
||||
of contents. |
||||
|
||||
Each transform is an optional step that a Docutils component may |
||||
choose to perform on the parsed document. |
||||
""" |
||||
|
||||
__docformat__ = 'reStructuredText' |
||||
|
||||
|
||||
from docutils import languages, ApplicationError, TransformSpec |
||||
|
||||
|
||||
class TransformError(ApplicationError): pass |
||||
|
||||
|
||||
class Transform: |
||||
|
||||
""" |
||||
Docutils transform component abstract base class. |
||||
""" |
||||
|
||||
default_priority = None |
||||
"""Numerical priority of this transform, 0 through 999 (override).""" |
||||
|
||||
def __init__(self, document, startnode=None): |
||||
""" |
||||
Initial setup for in-place document transforms. |
||||
""" |
||||
|
||||
self.document = document |
||||
"""The document tree to transform.""" |
||||
|
||||
self.startnode = startnode |
||||
"""Node from which to begin the transform. For many transforms which |
||||
apply to the document as a whole, `startnode` is not set (i.e. its |
||||
value is `None`).""" |
||||
|
||||
self.language = languages.get_language( |
||||
document.settings.language_code, document.reporter) |
||||
"""Language module local to this document.""" |
||||
|
||||
def apply(self, **kwargs): |
||||
"""Override to apply the transform to the document tree.""" |
||||
raise NotImplementedError('subclass must override this method') |
||||
|
||||
|
||||
class Transformer(TransformSpec): |
||||
|
||||
""" |
||||
Stores transforms (`Transform` classes) and applies them to document |
||||
trees. Also keeps track of components by component type name. |
||||
""" |
||||
|
||||
def __init__(self, document): |
||||
self.transforms = [] |
||||
"""List of transforms to apply. Each item is a 3-tuple: |
||||
``(priority string, transform class, pending node or None)``.""" |
||||
|
||||
self.unknown_reference_resolvers = [] |
||||
"""List of hook functions which assist in resolving references""" |
||||
|
||||
self.document = document |
||||
"""The `nodes.document` object this Transformer is attached to.""" |
||||
|
||||
self.applied = [] |
||||
"""Transforms already applied, in order.""" |
||||
|
||||
self.sorted = 0 |
||||
"""Boolean: is `self.tranforms` sorted?""" |
||||
|
||||
self.components = {} |
||||
"""Mapping of component type name to component object. Set by |
||||
`self.populate_from_components()`.""" |
||||
|
||||
self.serialno = 0 |
||||
"""Internal serial number to keep track of the add order of |
||||
transforms.""" |
||||
|
||||
def add_transform(self, transform_class, priority=None, **kwargs): |
||||
""" |
||||
Store a single transform. Use `priority` to override the default. |
||||
`kwargs` is a dictionary whose contents are passed as keyword |
||||
arguments to the `apply` method of the transform. This can be used to |
||||
pass application-specific data to the transform instance. |
||||
""" |
||||
if priority is None: |
||||
priority = transform_class.default_priority |
||||
priority_string = self.get_priority_string(priority) |
||||
self.transforms.append( |
||||
(priority_string, transform_class, None, kwargs)) |
||||
self.sorted = 0 |
||||
|
||||
def add_transforms(self, transform_list): |
||||
"""Store multiple transforms, with default priorities.""" |
||||
for transform_class in transform_list: |
||||
priority_string = self.get_priority_string( |
||||
transform_class.default_priority) |
||||
self.transforms.append( |
||||
(priority_string, transform_class, None, {})) |
||||
self.sorted = 0 |
||||
|
||||
def add_pending(self, pending, priority=None): |
||||
"""Store a transform with an associated `pending` node.""" |
||||
transform_class = pending.transform |
||||
if priority is None: |
||||
priority = transform_class.default_priority |
||||
priority_string = self.get_priority_string(priority) |
||||
self.transforms.append( |
||||
(priority_string, transform_class, pending, {})) |
||||
self.sorted = 0 |
||||
|
||||
def get_priority_string(self, priority): |
||||
""" |
||||
Return a string, `priority` combined with `self.serialno`. |
||||
|
||||
This ensures FIFO order on transforms with identical priority. |
||||
""" |
||||
self.serialno += 1 |
||||
return '%03d-%03d' % (priority, self.serialno) |
||||
|
||||
def populate_from_components(self, components): |
||||
""" |
||||
Store each component's default transforms, with default priorities. |
||||
Also, store components by type name in a mapping for later lookup. |
||||
""" |
||||
for component in components: |
||||
if component is None: |
||||
continue |
||||
self.add_transforms(component.get_transforms()) |
||||
self.components[component.component_type] = component |
||||
self.sorted = 0 |
||||
# Set up all of the reference resolvers for this transformer. Each |
||||
# component of this transformer is able to register its own helper |
||||
# functions to help resolve references. |
||||
unknown_reference_resolvers = [] |
||||
for i in components: |
||||
unknown_reference_resolvers.extend(i.unknown_reference_resolvers) |
||||
decorated_list = [(f.priority, f) for f in unknown_reference_resolvers] |
||||
decorated_list.sort() |
||||
self.unknown_reference_resolvers.extend([f[1] for f in decorated_list]) |
||||
|
||||
def apply_transforms(self): |
||||
"""Apply all of the stored transforms, in priority order.""" |
||||
self.document.reporter.attach_observer( |
||||
self.document.note_transform_message) |
||||
while self.transforms: |
||||
if not self.sorted: |
||||
# Unsorted initially, and whenever a transform is added. |
||||
self.transforms.sort() |
||||
self.transforms.reverse() |
||||
self.sorted = 1 |
||||
priority, transform_class, pending, kwargs = self.transforms.pop() |
||||
transform = transform_class(self.document, startnode=pending) |
||||
transform.apply(**kwargs) |
||||
self.applied.append((priority, transform_class, pending, kwargs)) |
||||
@ -0,0 +1,52 @@
|
||||
# $Id: components.py 4564 2006-05-21 20:44:42Z wiemann $ |
||||
# Author: David Goodger <goodger@python.org> |
||||
# Copyright: This module has been placed in the public domain. |
||||
|
||||
""" |
||||
Docutils component-related transforms. |
||||
""" |
||||
|
||||
__docformat__ = 'reStructuredText' |
||||
|
||||
import sys |
||||
import os |
||||
import re |
||||
import time |
||||
from docutils import nodes, utils |
||||
from docutils import ApplicationError, DataError |
||||
from docutils.transforms import Transform, TransformError |
||||
|
||||
|
||||
class Filter(Transform): |
||||
|
||||
""" |
||||
Include or exclude elements which depend on a specific Docutils component. |
||||
|
||||
For use with `nodes.pending` elements. A "pending" element's dictionary |
||||
attribute ``details`` must contain the keys "component" and "format". The |
||||
value of ``details['component']`` must match the type name of the |
||||
component the elements depend on (e.g. "writer"). The value of |
||||
``details['format']`` is the name of a specific format or context of that |
||||
component (e.g. "html"). If the matching Docutils component supports that |
||||
format or context, the "pending" element is replaced by the contents of |
||||
``details['nodes']`` (a list of nodes); otherwise, the "pending" element |
||||
is removed. |
||||
|
||||
For example, the reStructuredText "meta" directive creates a "pending" |
||||
element containing a "meta" element (in ``pending.details['nodes']``). |
||||
Only writers (``pending.details['component'] == 'writer'``) supporting the |
||||
"html" format (``pending.details['format'] == 'html'``) will include the |
||||
"meta" element; it will be deleted from the output of all other writers. |
||||
""" |
||||
|
||||
default_priority = 780 |
||||
|
||||
def apply(self): |
||||
pending = self.startnode |
||||
component_type = pending.details['component'] # 'reader' or 'writer' |
||||
format = pending.details['format'] |
||||
component = self.document.transformer.components[component_type] |
||||
if component.supports(format): |
||||
pending.replace_self(pending.details['nodes']) |
||||
else: |
||||
pending.parent.remove(pending) |
||||
@ -0,0 +1,532 @@
|
||||
# $Id: frontmatter.py 8117 2017-06-18 23:38:18Z milde $ |
||||
# Author: David Goodger, Ueli Schlaepfer <goodger@python.org> |
||||
# Copyright: This module has been placed in the public domain. |
||||
|
||||
""" |
||||
Transforms related to the front matter of a document or a section |
||||
(information found before the main text): |
||||
|
||||
- `DocTitle`: Used to transform a lone top level section's title to |
||||
the document title, promote a remaining lone top-level section's |
||||
title to the document subtitle, and determine the document's title |
||||
metadata (document['title']) based on the document title and/or the |
||||
"title" setting. |
||||
|
||||
- `SectionSubTitle`: Used to transform a lone subsection into a |
||||
subtitle. |
||||
|
||||
- `DocInfo`: Used to transform a bibliographic field list into docinfo |
||||
elements. |
||||
""" |
||||
|
||||
__docformat__ = 'reStructuredText' |
||||
|
||||
import re |
||||
from docutils import nodes, utils |
||||
from docutils.transforms import TransformError, Transform |
||||
|
||||
|
||||
class TitlePromoter(Transform): |
||||
|
||||
""" |
||||
Abstract base class for DocTitle and SectionSubTitle transforms. |
||||
""" |
||||
|
||||
def promote_title(self, node): |
||||
""" |
||||
Transform the following tree:: |
||||
|
||||
<node> |
||||
<section> |
||||
<title> |
||||
... |
||||
|
||||
into :: |
||||
|
||||
<node> |
||||
<title> |
||||
... |
||||
|
||||
`node` is normally a document. |
||||
""" |
||||
# Type check |
||||
if not isinstance(node, nodes.Element): |
||||
raise TypeError, 'node must be of Element-derived type.' |
||||
|
||||
# `node` must not have a title yet. |
||||
assert not (len(node) and isinstance(node[0], nodes.title)) |
||||
section, index = self.candidate_index(node) |
||||
if index is None: |
||||
return None |
||||
|
||||
# Transfer the section's attributes to the node: |
||||
# NOTE: Change second parameter to False to NOT replace |
||||
# attributes that already exist in node with those in |
||||
# section |
||||
# NOTE: Remove third parameter to NOT copy the 'source' |
||||
# attribute from section |
||||
node.update_all_atts_concatenating(section, True, True) |
||||
|
||||
# setup_child is called automatically for all nodes. |
||||
node[:] = (section[:1] # section title |
||||
+ node[:index] # everything that was in the |
||||
# node before the section |
||||
+ section[1:]) # everything that was in the section |
||||
assert isinstance(node[0], nodes.title) |
||||
return 1 |
||||
|
||||
def promote_subtitle(self, node): |
||||
""" |
||||
Transform the following node tree:: |
||||
|
||||
<node> |
||||
<title> |
||||
<section> |
||||
<title> |
||||
... |
||||
|
||||
into :: |
||||
|
||||
<node> |
||||
<title> |
||||
<subtitle> |
||||
... |
||||
""" |
||||
# Type check |
||||
if not isinstance(node, nodes.Element): |
||||
raise TypeError, 'node must be of Element-derived type.' |
||||
|
||||
subsection, index = self.candidate_index(node) |
||||
if index is None: |
||||
return None |
||||
subtitle = nodes.subtitle() |
||||
|
||||
# Transfer the subsection's attributes to the new subtitle |
||||
# NOTE: Change second parameter to False to NOT replace |
||||
# attributes that already exist in node with those in |
||||
# section |
||||
# NOTE: Remove third parameter to NOT copy the 'source' |
||||
# attribute from section |
||||
subtitle.update_all_atts_concatenating(subsection, True, True) |
||||
|
||||
# Transfer the contents of the subsection's title to the |
||||
# subtitle: |
||||
subtitle[:] = subsection[0][:] |
||||
node[:] = (node[:1] # title |
||||
+ [subtitle] |
||||
# everything that was before the section: |
||||
+ node[1:index] |
||||
# everything that was in the subsection: |
||||
+ subsection[1:]) |
||||
return 1 |
||||
|
||||
def candidate_index(self, node): |
||||
""" |
||||
Find and return the promotion candidate and its index. |
||||
|
||||
Return (None, None) if no valid candidate was found. |
||||
""" |
||||
index = node.first_child_not_matching_class( |
||||
nodes.PreBibliographic) |
||||
if index is None or len(node) > (index + 1) or \ |
||||
not isinstance(node[index], nodes.section): |
||||
return None, None |
||||
else: |
||||
return node[index], index |
||||
|
||||
|
||||
class DocTitle(TitlePromoter): |
||||
|
||||
""" |
||||
In reStructuredText_, there is no way to specify a document title |
||||
and subtitle explicitly. Instead, we can supply the document title |
||||
(and possibly the subtitle as well) implicitly, and use this |
||||
two-step transform to "raise" or "promote" the title(s) (and their |
||||
corresponding section contents) to the document level. |
||||
|
||||
1. If the document contains a single top-level section as its |
||||
first non-comment element, the top-level section's title |
||||
becomes the document's title, and the top-level section's |
||||
contents become the document's immediate contents. The lone |
||||
top-level section header must be the first non-comment element |
||||
in the document. |
||||
|
||||
For example, take this input text:: |
||||
|
||||
================= |
||||
Top-Level Title |
||||
================= |
||||
|
||||
A paragraph. |
||||
|
||||
Once parsed, it looks like this:: |
||||
|
||||
<document> |
||||
<section names="top-level title"> |
||||
<title> |
||||
Top-Level Title |
||||
<paragraph> |
||||
A paragraph. |
||||
|
||||
After running the DocTitle transform, we have:: |
||||
|
||||
<document names="top-level title"> |
||||
<title> |
||||
Top-Level Title |
||||
<paragraph> |
||||
A paragraph. |
||||
|
||||
2. If step 1 successfully determines the document title, we |
||||
continue by checking for a subtitle. |
||||
|
||||
If the lone top-level section itself contains a single |
||||
second-level section as its first non-comment element, that |
||||
section's title is promoted to the document's subtitle, and |
||||
that section's contents become the document's immediate |
||||
contents. Given this input text:: |
||||
|
||||
================= |
||||
Top-Level Title |
||||
================= |
||||
|
||||
Second-Level Title |
||||
~~~~~~~~~~~~~~~~~~ |
||||
|
||||
A paragraph. |
||||
|
||||
After parsing and running the Section Promotion transform, the |
||||
result is:: |
||||
|
||||
<document names="top-level title"> |
||||
<title> |
||||
Top-Level Title |
||||
<subtitle names="second-level title"> |
||||
Second-Level Title |
||||
<paragraph> |
||||
A paragraph. |
||||
|
||||
(Note that the implicit hyperlink target generated by the |
||||
"Second-Level Title" is preserved on the "subtitle" element |
||||
itself.) |
||||
|
||||
Any comment elements occurring before the document title or |
||||
subtitle are accumulated and inserted as the first body elements |
||||
after the title(s). |
||||
|
||||
This transform also sets the document's metadata title |
||||
(document['title']). |
||||
|
||||
.. _reStructuredText: http://docutils.sf.net/rst.html |
||||
""" |
||||
|
||||
default_priority = 320 |
||||
|
||||
def set_metadata(self): |
||||
""" |
||||
Set document['title'] metadata title from the following |
||||
sources, listed in order of priority: |
||||
|
||||
* Existing document['title'] attribute. |
||||
* "title" setting. |
||||
* Document title node (as promoted by promote_title). |
||||
""" |
||||
if not self.document.hasattr('title'): |
||||
if self.document.settings.title is not None: |
||||
self.document['title'] = self.document.settings.title |
||||
elif len(self.document) and isinstance(self.document[0], nodes.title): |
||||
self.document['title'] = self.document[0].astext() |
||||
|
||||
def apply(self): |
||||
if getattr(self.document.settings, 'doctitle_xform', 1): |
||||
# promote_(sub)title defined in TitlePromoter base class. |
||||
if self.promote_title(self.document): |
||||
# If a title has been promoted, also try to promote a |
||||
# subtitle. |
||||
self.promote_subtitle(self.document) |
||||
# Set document['title']. |
||||
self.set_metadata() |
||||
|
||||
|
||||
class SectionSubTitle(TitlePromoter): |
||||
|
||||
""" |
||||
This works like document subtitles, but for sections. For example, :: |
||||
|
||||
<section> |
||||
<title> |
||||
Title |
||||
<section> |
||||
<title> |
||||
Subtitle |
||||
... |
||||
|
||||
is transformed into :: |
||||
|
||||
<section> |
||||
<title> |
||||
Title |
||||
<subtitle> |
||||
Subtitle |
||||
... |
||||
|
||||
For details refer to the docstring of DocTitle. |
||||
""" |
||||
|
||||
default_priority = 350 |
||||
|
||||
def apply(self): |
||||
if not getattr(self.document.settings, 'sectsubtitle_xform', 1): |
||||
return |
||||
for section in self.document.traverse(nodes.section): |
||||
# On our way through the node tree, we are deleting |
||||
# sections, but we call self.promote_subtitle for those |
||||
# sections nonetheless. To do: Write a test case which |
||||
# shows the problem and discuss on Docutils-develop. |
||||
self.promote_subtitle(section) |
||||
|
||||
|
||||
class DocInfo(Transform): |
||||
|
||||
""" |
||||
This transform is specific to the reStructuredText_ markup syntax; |
||||
see "Bibliographic Fields" in the `reStructuredText Markup |
||||
Specification`_ for a high-level description. This transform |
||||
should be run *after* the `DocTitle` transform. |
||||
|
||||
Given a field list as the first non-comment element after the |
||||
document title and subtitle (if present), registered bibliographic |
||||
field names are transformed to the corresponding DTD elements, |
||||
becoming child elements of the "docinfo" element (except for a |
||||
dedication and/or an abstract, which become "topic" elements after |
||||
"docinfo"). |
||||
|
||||
For example, given this document fragment after parsing:: |
||||
|
||||
<document> |
||||
<title> |
||||
Document Title |
||||
<field_list> |
||||
<field> |
||||
<field_name> |
||||
Author |
||||
<field_body> |
||||
<paragraph> |
||||
A. Name |
||||
<field> |
||||
<field_name> |
||||
Status |
||||
<field_body> |
||||
<paragraph> |
||||
$RCSfile$ |
||||
... |
||||
|
||||
After running the bibliographic field list transform, the |
||||
resulting document tree would look like this:: |
||||
|
||||
<document> |
||||
<title> |
||||
Document Title |
||||
<docinfo> |
||||
<author> |
||||
A. Name |
||||
<status> |
||||
frontmatter.py |
||||
... |
||||
|
||||
The "Status" field contained an expanded RCS keyword, which is |
||||
normally (but optionally) cleaned up by the transform. The sole |
||||
contents of the field body must be a paragraph containing an |
||||
expanded RCS keyword of the form "$keyword: expansion text $". Any |
||||
RCS keyword can be processed in any bibliographic field. The |
||||
dollar signs and leading RCS keyword name are removed. Extra |
||||
processing is done for the following RCS keywords: |
||||
|
||||
- "RCSfile" expands to the name of the file in the RCS or CVS |
||||
repository, which is the name of the source file with a ",v" |
||||
suffix appended. The transform will remove the ",v" suffix. |
||||
|
||||
- "Date" expands to the format "YYYY/MM/DD hh:mm:ss" (in the UTC |
||||
time zone). The RCS Keywords transform will extract just the |
||||
date itself and transform it to an ISO 8601 format date, as in |
||||
"2000-12-31". |
||||
|
||||
(Since the source file for this text is itself stored under CVS, |
||||
we can't show an example of the "Date" RCS keyword because we |
||||
can't prevent any RCS keywords used in this explanation from |
||||
being expanded. Only the "RCSfile" keyword is stable; its |
||||
expansion text changes only if the file name changes.) |
||||
|
||||
.. _reStructuredText: http://docutils.sf.net/rst.html |
||||
.. _reStructuredText Markup Specification: |
||||
http://docutils.sf.net/docs/ref/rst/restructuredtext.html |
||||
""" |
||||
|
||||
default_priority = 340 |
||||
|
||||
biblio_nodes = { |
||||
'author': nodes.author, |
||||
'authors': nodes.authors, |
||||
'organization': nodes.organization, |
||||
'address': nodes.address, |
||||
'contact': nodes.contact, |
||||
'version': nodes.version, |
||||
'revision': nodes.revision, |
||||
'status': nodes.status, |
||||
'date': nodes.date, |
||||
'copyright': nodes.copyright, |
||||
'dedication': nodes.topic, |
||||
'abstract': nodes.topic} |
||||
"""Canonical field name (lowcased) to node class name mapping for |
||||
bibliographic fields (field_list).""" |
||||
|
||||
def apply(self): |
||||
if not getattr(self.document.settings, 'docinfo_xform', 1): |
||||
return |
||||
document = self.document |
||||
index = document.first_child_not_matching_class( |
||||
nodes.PreBibliographic) |
||||
if index is None: |
||||
return |
||||
candidate = document[index] |
||||
if isinstance(candidate, nodes.field_list): |
||||
biblioindex = document.first_child_not_matching_class( |
||||
(nodes.Titular, nodes.Decorative)) |
||||
nodelist = self.extract_bibliographic(candidate) |
||||
del document[index] # untransformed field list (candidate) |
||||
document[biblioindex:biblioindex] = nodelist |
||||
|
||||
def extract_bibliographic(self, field_list): |
||||
docinfo = nodes.docinfo() |
||||
bibliofields = self.language.bibliographic_fields |
||||
labels = self.language.labels |
||||
topics = {'dedication': None, 'abstract': None} |
||||
for field in field_list: |
||||
try: |
||||
name = field[0][0].astext() |
||||
normedname = nodes.fully_normalize_name(name) |
||||
if not (len(field) == 2 and normedname in bibliofields |
||||
and self.check_empty_biblio_field(field, name)): |
||||
raise TransformError |
||||
canonical = bibliofields[normedname] |
||||
biblioclass = self.biblio_nodes[canonical] |
||||
if issubclass(biblioclass, nodes.TextElement): |
||||
if not self.check_compound_biblio_field(field, name): |
||||
raise TransformError |
||||
utils.clean_rcs_keywords( |
||||
field[1][0], self.rcs_keyword_substitutions) |
||||
docinfo.append(biblioclass('', '', *field[1][0])) |
||||
elif issubclass(biblioclass, nodes.authors): |
||||
self.extract_authors(field, name, docinfo) |
||||
elif issubclass(biblioclass, nodes.topic): |
||||
if topics[canonical]: |
||||
field[-1] += self.document.reporter.warning( |
||||
'There can only be one "%s" field.' % name, |
||||
base_node=field) |
||||
raise TransformError |
||||
title = nodes.title(name, labels[canonical]) |
||||
topics[canonical] = biblioclass( |
||||
'', title, classes=[canonical], *field[1].children) |
||||
else: |
||||
docinfo.append(biblioclass('', *field[1].children)) |
||||
except TransformError: |
||||
if len(field[-1]) == 1 \ |
||||
and isinstance(field[-1][0], nodes.paragraph): |
||||
utils.clean_rcs_keywords( |
||||
field[-1][0], self.rcs_keyword_substitutions) |
||||
if normedname not in bibliofields: |
||||
classvalue = nodes.make_id(normedname) |
||||
if classvalue: |
||||
field['classes'].append(classvalue) |
||||
docinfo.append(field) |
||||
nodelist = [] |
||||
if len(docinfo) != 0: |
||||
nodelist.append(docinfo) |
||||
for name in ('dedication', 'abstract'): |
||||
if topics[name]: |
||||
nodelist.append(topics[name]) |
||||
return nodelist |
||||
|
||||
def check_empty_biblio_field(self, field, name): |
||||
if len(field[-1]) < 1: |
||||
field[-1] += self.document.reporter.warning( |
||||
'Cannot extract empty bibliographic field "%s".' % name, |
||||
base_node=field) |
||||
return None |
||||
return 1 |
||||
|
||||
def check_compound_biblio_field(self, field, name): |
||||
if len(field[-1]) > 1: |
||||
field[-1] += self.document.reporter.warning( |
||||
'Cannot extract compound bibliographic field "%s".' % name, |
||||
base_node=field) |
||||
return None |
||||
if not isinstance(field[-1][0], nodes.paragraph): |
||||
field[-1] += self.document.reporter.warning( |
||||
'Cannot extract bibliographic field "%s" containing ' |
||||
'anything other than a single paragraph.' % name, |
||||
base_node=field) |
||||
return None |
||||
return 1 |
||||
|
||||
rcs_keyword_substitutions = [ |
||||
(re.compile(r'\$' r'Date: (\d\d\d\d)[-/](\d\d)[-/](\d\d)[ T][\d:]+' |
||||
r'[^$]* \$', re.IGNORECASE), r'\1-\2-\3'), |
||||
(re.compile(r'\$' r'RCSfile: (.+),v \$', re.IGNORECASE), r'\1'), |
||||
(re.compile(r'\$[a-zA-Z]+: (.+) \$'), r'\1'),] |
||||
|
||||
def extract_authors(self, field, name, docinfo): |
||||
try: |
||||
if len(field[1]) == 1: |
||||
if isinstance(field[1][0], nodes.paragraph): |
||||
authors = self.authors_from_one_paragraph(field) |
||||
elif isinstance(field[1][0], nodes.bullet_list): |
||||
authors = self.authors_from_bullet_list(field) |
||||
else: |
||||
raise TransformError |
||||
else: |
||||
authors = self.authors_from_paragraphs(field) |
||||
authornodes = [nodes.author('', '', *author) |
||||
for author in authors if author] |
||||
if len(authornodes) >= 1: |
||||
docinfo.append(nodes.authors('', *authornodes)) |
||||
else: |
||||
raise TransformError |
||||
except TransformError: |
||||
field[-1] += self.document.reporter.warning( |
||||
'Bibliographic field "%s" incompatible with extraction: ' |
||||
'it must contain either a single paragraph (with authors ' |
||||
'separated by one of "%s"), multiple paragraphs (one per ' |
||||
'author), or a bullet list with one paragraph (one author) ' |
||||
'per item.' |
||||
% (name, ''.join(self.language.author_separators)), |
||||
base_node=field) |
||||
raise |
||||
|
||||
def authors_from_one_paragraph(self, field): |
||||
text = field[1][0].astext().strip() |
||||
if not text: |
||||
raise TransformError |
||||
for authorsep in self.language.author_separators: |
||||
authornames = text.split(authorsep) |
||||
if len(authornames) > 1: |
||||
break |
||||
authornames = [author.strip() for author in authornames] |
||||
authors = [[nodes.Text(author)] for author in authornames if author] |
||||
return authors |
||||
|
||||
def authors_from_bullet_list(self, field): |
||||
authors = [] |
||||
for item in field[1][0]: |
||||
if len(item) != 1 or not isinstance(item[0], nodes.paragraph): |
||||
raise TransformError |
||||
authors.append(item[0].children) |
||||
if not authors: |
||||
raise TransformError |
||||
return authors |
||||
|
||||
def authors_from_paragraphs(self, field): |
||||
for item in field[1]: |
||||
if not isinstance(item, nodes.paragraph): |
||||
raise TransformError |
||||
authors = [item.children for item in field[1]] |
||||
return authors |
||||
@ -0,0 +1,144 @@
|
||||
# $Id: misc.py 6314 2010-04-26 10:04:17Z milde $ |
||||
# Author: David Goodger <goodger@python.org> |
||||
# Copyright: This module has been placed in the public domain. |
||||
|
||||
""" |
||||
Miscellaneous transforms. |
||||
""" |
||||
|
||||
__docformat__ = 'reStructuredText' |
||||
|
||||
from docutils import nodes |
||||
from docutils.transforms import Transform, TransformError |
||||
|
||||
|
||||
class CallBack(Transform): |
||||
|
||||
""" |
||||
Inserts a callback into a document. The callback is called when the |
||||
transform is applied, which is determined by its priority. |
||||
|
||||
For use with `nodes.pending` elements. Requires a ``details['callback']`` |
||||
entry, a bound method or function which takes one parameter: the pending |
||||
node. Other data can be stored in the ``details`` attribute or in the |
||||
object hosting the callback method. |
||||
""" |
||||
|
||||
default_priority = 990 |
||||
|
||||
def apply(self): |
||||
pending = self.startnode |
||||
pending.details['callback'](pending) |
||||
pending.parent.remove(pending) |
||||
|
||||
|
||||
class ClassAttribute(Transform): |
||||
|
||||
""" |
||||
Move the "class" attribute specified in the "pending" node into the |
||||
immediately following non-comment element. |
||||
""" |
||||
|
||||
default_priority = 210 |
||||
|
||||
def apply(self): |
||||
pending = self.startnode |
||||
parent = pending.parent |
||||
child = pending |
||||
while parent: |
||||
# Check for appropriate following siblings: |
||||
for index in range(parent.index(child) + 1, len(parent)): |
||||
element = parent[index] |
||||
if (isinstance(element, nodes.Invisible) or |
||||
isinstance(element, nodes.system_message)): |
||||
continue |
||||
element['classes'] += pending.details['class'] |
||||
pending.parent.remove(pending) |
||||
return |
||||
else: |
||||
# At end of section or container; apply to sibling |
||||
child = parent |
||||
parent = parent.parent |
||||
error = self.document.reporter.error( |
||||
'No suitable element following "%s" directive' |
||||
% pending.details['directive'], |
||||
nodes.literal_block(pending.rawsource, pending.rawsource), |
||||
line=pending.line) |
||||
pending.replace_self(error) |
||||
|
||||
|
||||
class Transitions(Transform): |
||||
|
||||
""" |
||||
Move transitions at the end of sections up the tree. Complain |
||||
on transitions after a title, at the beginning or end of the |
||||
document, and after another transition. |
||||
|
||||
For example, transform this:: |
||||
|
||||
<section> |
||||
... |
||||
<transition> |
||||
<section> |
||||
... |
||||
|
||||
into this:: |
||||
|
||||
<section> |
||||
... |
||||
<transition> |
||||
<section> |
||||
... |
||||
""" |
||||
|
||||
default_priority = 830 |
||||
|
||||
def apply(self): |
||||
for node in self.document.traverse(nodes.transition): |
||||
self.visit_transition(node) |
||||
|
||||
def visit_transition(self, node): |
||||
index = node.parent.index(node) |
||||
error = None |
||||
if (index == 0 or |
||||
isinstance(node.parent[0], nodes.title) and |
||||
(index == 1 or |
||||
isinstance(node.parent[1], nodes.subtitle) and |
||||
index == 2)): |
||||
assert (isinstance(node.parent, nodes.document) or |
||||
isinstance(node.parent, nodes.section)) |
||||
error = self.document.reporter.error( |
||||
'Document or section may not begin with a transition.', |
||||
source=node.source, line=node.line) |
||||
elif isinstance(node.parent[index - 1], nodes.transition): |
||||
error = self.document.reporter.error( |
||||
'At least one body element must separate transitions; ' |
||||
'adjacent transitions are not allowed.', |
||||
source=node.source, line=node.line) |
||||
if error: |
||||
# Insert before node and update index. |
||||
node.parent.insert(index, error) |
||||
index += 1 |
||||
assert index < len(node.parent) |
||||
if index != len(node.parent) - 1: |
||||
# No need to move the node. |
||||
return |
||||
# Node behind which the transition is to be moved. |
||||
sibling = node |
||||
# While sibling is the last node of its parent. |
||||
while index == len(sibling.parent) - 1: |
||||
sibling = sibling.parent |
||||
# If sibling is the whole document (i.e. it has no parent). |
||||
if sibling.parent is None: |
||||
# Transition at the end of document. Do not move the |
||||
# transition up, and place an error behind. |
||||
error = self.document.reporter.error( |
||||
'Document may not end with a transition.', |
||||
line=node.line) |
||||
node.parent.insert(node.parent.index(node) + 1, error) |
||||
return |
||||
index = sibling.parent.index(sibling) |
||||
# Remove the original transition node. |
||||
node.parent.remove(node) |
||||
# Insert the transition after the sibling. |
||||
sibling.parent.insert(index + 1, node) |
||||
@ -0,0 +1,180 @@
|
||||
# $Id: parts.py 6073 2009-08-06 12:21:10Z milde $ |
||||
# Authors: David Goodger <goodger@python.org>; Ueli Schlaepfer; Dmitry Jemerov |
||||
# Copyright: This module has been placed in the public domain. |
||||
|
||||
""" |
||||
Transforms related to document parts. |
||||
""" |
||||
|
||||
__docformat__ = 'reStructuredText' |
||||
|
||||
|
||||
import re |
||||
import sys |
||||
from docutils import nodes, utils |
||||
from docutils.transforms import TransformError, Transform |
||||
|
||||
|
||||
class SectNum(Transform): |
||||
|
||||
""" |
||||
Automatically assigns numbers to the titles of document sections. |
||||
|
||||
It is possible to limit the maximum section level for which the numbers |
||||
are added. For those sections that are auto-numbered, the "autonum" |
||||
attribute is set, informing the contents table generator that a different |
||||
form of the TOC should be used. |
||||
""" |
||||
|
||||
default_priority = 710 |
||||
"""Should be applied before `Contents`.""" |
||||
|
||||
def apply(self): |
||||
self.maxdepth = self.startnode.details.get('depth', None) |
||||
self.startvalue = self.startnode.details.get('start', 1) |
||||
self.prefix = self.startnode.details.get('prefix', '') |
||||
self.suffix = self.startnode.details.get('suffix', '') |
||||
self.startnode.parent.remove(self.startnode) |
||||
if self.document.settings.sectnum_xform: |
||||
if self.maxdepth is None: |
||||
self.maxdepth = sys.maxint |
||||
self.update_section_numbers(self.document) |
||||
else: # store details for eventual section numbering by the writer |
||||
self.document.settings.sectnum_depth = self.maxdepth |
||||
self.document.settings.sectnum_start = self.startvalue |
||||
self.document.settings.sectnum_prefix = self.prefix |
||||
self.document.settings.sectnum_suffix = self.suffix |
||||
|
||||
def update_section_numbers(self, node, prefix=(), depth=0): |
||||
depth += 1 |
||||
if prefix: |
||||
sectnum = 1 |
||||
else: |
||||
sectnum = self.startvalue |
||||
for child in node: |
||||
if isinstance(child, nodes.section): |
||||
numbers = prefix + (str(sectnum),) |
||||
title = child[0] |
||||
# Use for spacing: |
||||
generated = nodes.generated( |
||||
'', (self.prefix + '.'.join(numbers) + self.suffix |
||||
+ u'\u00a0' * 3), |
||||
classes=['sectnum']) |
||||
title.insert(0, generated) |
||||
title['auto'] = 1 |
||||
if depth < self.maxdepth: |
||||
self.update_section_numbers(child, numbers, depth) |
||||
sectnum += 1 |
||||
|
||||
|
||||
class Contents(Transform): |
||||
|
||||
""" |
||||
This transform generates a table of contents from the entire document tree |
||||
or from a single branch. It locates "section" elements and builds them |
||||
into a nested bullet list, which is placed within a "topic" created by the |
||||
contents directive. A title is either explicitly specified, taken from |
||||
the appropriate language module, or omitted (local table of contents). |
||||
The depth may be specified. Two-way references between the table of |
||||
contents and section titles are generated (requires Writer support). |
||||
|
||||
This transform requires a startnode, which contains generation |
||||
options and provides the location for the generated table of contents (the |
||||
startnode is replaced by the table of contents "topic"). |
||||
""" |
||||
|
||||
default_priority = 720 |
||||
|
||||
def apply(self): |
||||
try: # let the writer (or output software) build the contents list? |
||||
toc_by_writer = self.document.settings.use_latex_toc |
||||
except AttributeError: |
||||
toc_by_writer = False |
||||
details = self.startnode.details |
||||
if 'local' in details: |
||||
startnode = self.startnode.parent.parent |
||||
while not (isinstance(startnode, nodes.section) |
||||
or isinstance(startnode, nodes.document)): |
||||
# find the ToC root: a direct ancestor of startnode |
||||
startnode = startnode.parent |
||||
else: |
||||
startnode = self.document |
||||
self.toc_id = self.startnode.parent['ids'][0] |
||||
if 'backlinks' in details: |
||||
self.backlinks = details['backlinks'] |
||||
else: |
||||
self.backlinks = self.document.settings.toc_backlinks |
||||
if toc_by_writer: |
||||
# move customization settings to the parent node |
||||
self.startnode.parent.attributes.update(details) |
||||
self.startnode.parent.remove(self.startnode) |
||||
else: |
||||
contents = self.build_contents(startnode) |
||||
if len(contents): |
||||
self.startnode.replace_self(contents) |
||||
else: |
||||
self.startnode.parent.parent.remove(self.startnode.parent) |
||||
|
||||
def build_contents(self, node, level=0): |
||||
level += 1 |
||||
sections = [sect for sect in node if isinstance(sect, nodes.section)] |
||||
entries = [] |
||||
autonum = 0 |
||||
depth = self.startnode.details.get('depth', sys.maxint) |
||||
for section in sections: |
||||
title = section[0] |
||||
auto = title.get('auto') # May be set by SectNum. |
||||
entrytext = self.copy_and_filter(title) |
||||
reference = nodes.reference('', '', refid=section['ids'][0], |
||||
*entrytext) |
||||
ref_id = self.document.set_id(reference) |
||||
entry = nodes.paragraph('', '', reference) |
||||
item = nodes.list_item('', entry) |
||||
if ( self.backlinks in ('entry', 'top') |
||||
and title.next_node(nodes.reference) is None): |
||||
if self.backlinks == 'entry': |
||||
title['refid'] = ref_id |
||||
elif self.backlinks == 'top': |
||||
title['refid'] = self.toc_id |
||||
if level < depth: |
||||
subsects = self.build_contents(section, level) |
||||
item += subsects |
||||
entries.append(item) |
||||
if entries: |
||||
contents = nodes.bullet_list('', *entries) |
||||
if auto: |
||||
contents['classes'].append('auto-toc') |
||||
return contents |
||||
else: |
||||
return [] |
||||
|
||||
def copy_and_filter(self, node): |
||||
"""Return a copy of a title, with references, images, etc. removed.""" |
||||
visitor = ContentsFilter(self.document) |
||||
node.walkabout(visitor) |
||||
return visitor.get_entry_text() |
||||
|
||||
|
||||
class ContentsFilter(nodes.TreeCopyVisitor): |
||||
|
||||
def get_entry_text(self): |
||||
return self.get_tree_copy().children |
||||
|
||||
def visit_citation_reference(self, node): |
||||
raise nodes.SkipNode |
||||
|
||||
def visit_footnote_reference(self, node): |
||||
raise nodes.SkipNode |
||||
|
||||
def visit_image(self, node): |
||||
if node.hasattr('alt'): |
||||
self.parent.append(nodes.Text(node['alt'])) |
||||
raise nodes.SkipNode |
||||
|
||||
def ignore_node_but_process_children(self, node): |
||||
raise nodes.SkipDeparture |
||||
|
||||
visit_interpreted = ignore_node_but_process_children |
||||
visit_problematic = ignore_node_but_process_children |
||||
visit_reference = ignore_node_but_process_children |
||||
visit_target = ignore_node_but_process_children |
||||
@ -0,0 +1,305 @@
|
||||
# $Id: peps.py 7995 2016-12-10 17:50:59Z milde $ |
||||
# Author: David Goodger <goodger@python.org> |
||||
# Copyright: This module has been placed in the public domain. |
||||
|
||||
""" |
||||
Transforms for PEP processing. |
||||
|
||||
- `Headers`: Used to transform a PEP's initial RFC-2822 header. It remains a |
||||
field list, but some entries get processed. |
||||
- `Contents`: Auto-inserts a table of contents. |
||||
- `PEPZero`: Special processing for PEP 0. |
||||
""" |
||||
|
||||
__docformat__ = 'reStructuredText' |
||||
|
||||
import sys |
||||
import os |
||||
import re |
||||
import time |
||||
from docutils import nodes, utils, languages |
||||
from docutils import ApplicationError, DataError |
||||
from docutils.transforms import Transform, TransformError |
||||
from docutils.transforms import parts, references, misc |
||||
|
||||
|
||||
class Headers(Transform): |
||||
|
||||
""" |
||||
Process fields in a PEP's initial RFC-2822 header. |
||||
""" |
||||
|
||||
default_priority = 360 |
||||
|
||||
pep_url = 'pep-%04d' |
||||
pep_cvs_url = ('http://hg.python.org' |
||||
'/peps/file/default/pep-%04d.txt') |
||||
rcs_keyword_substitutions = ( |
||||
(re.compile(r'\$' r'RCSfile: (.+),v \$$', re.IGNORECASE), r'\1'), |
||||
(re.compile(r'\$[a-zA-Z]+: (.+) \$$'), r'\1'),) |
||||
|
||||
def apply(self): |
||||
if not len(self.document): |
||||
# @@@ replace these DataErrors with proper system messages |
||||
raise DataError('Document tree is empty.') |
||||
header = self.document[0] |
||||
if not isinstance(header, nodes.field_list) or \ |
||||
'rfc2822' not in header['classes']: |
||||
raise DataError('Document does not begin with an RFC-2822 ' |
||||
'header; it is not a PEP.') |
||||
pep = None |
||||
for field in header: |
||||
if field[0].astext().lower() == 'pep': # should be the first field |
||||
value = field[1].astext() |
||||
try: |
||||
pep = int(value) |
||||
cvs_url = self.pep_cvs_url % pep |
||||
except ValueError: |
||||
pep = value |
||||
cvs_url = None |
||||
msg = self.document.reporter.warning( |
||||
'"PEP" header must contain an integer; "%s" is an ' |
||||
'invalid value.' % pep, base_node=field) |
||||
msgid = self.document.set_id(msg) |
||||
prb = nodes.problematic(value, value or '(none)', |
||||
refid=msgid) |
||||
prbid = self.document.set_id(prb) |
||||
msg.add_backref(prbid) |
||||
if len(field[1]): |
||||
field[1][0][:] = [prb] |
||||
else: |
||||
field[1] += nodes.paragraph('', '', prb) |
||||
break |
||||
if pep is None: |
||||
raise DataError('Document does not contain an RFC-2822 "PEP" ' |
||||
'header.') |
||||
if pep == 0: |
||||
# Special processing for PEP 0. |
||||
pending = nodes.pending(PEPZero) |
||||
self.document.insert(1, pending) |
||||
self.document.note_pending(pending) |
||||
if len(header) < 2 or header[1][0].astext().lower() != 'title': |
||||
raise DataError('No title!') |
||||
for field in header: |
||||
name = field[0].astext().lower() |
||||
body = field[1] |
||||
if len(body) > 1: |
||||
raise DataError('PEP header field body contains multiple ' |
||||
'elements:\n%s' % field.pformat(level=1)) |
||||
elif len(body) == 1: |
||||
if not isinstance(body[0], nodes.paragraph): |
||||
raise DataError('PEP header field body may only contain ' |
||||
'a single paragraph:\n%s' |
||||
% field.pformat(level=1)) |
||||
elif name == 'last-modified': |
||||
date = time.strftime( |
||||
'%d-%b-%Y', |
||||
time.localtime(os.stat(self.document['source'])[8])) |
||||
if cvs_url: |
||||
body += nodes.paragraph( |
||||
'', '', nodes.reference('', date, refuri=cvs_url)) |
||||
else: |
||||
# empty |
||||
continue |
||||
para = body[0] |
||||
if name == 'author': |
||||
for node in para: |
||||
if isinstance(node, nodes.reference): |
||||
node.replace_self(mask_email(node)) |
||||
elif name == 'discussions-to': |
||||
for node in para: |
||||
if isinstance(node, nodes.reference): |
||||
node.replace_self(mask_email(node, pep)) |
||||
elif name in ('replaces', 'replaced-by', 'requires'): |
||||
newbody = [] |
||||
space = nodes.Text(' ') |
||||
for refpep in re.split(r',?\s+', body.astext()): |
||||
pepno = int(refpep) |
||||
newbody.append(nodes.reference( |
||||
refpep, refpep, |
||||
refuri=(self.document.settings.pep_base_url |
||||
+ self.pep_url % pepno))) |
||||
newbody.append(space) |
||||
para[:] = newbody[:-1] # drop trailing space |
||||
elif name == 'last-modified': |
||||
utils.clean_rcs_keywords(para, self.rcs_keyword_substitutions) |
||||
if cvs_url: |
||||
date = para.astext() |
||||
para[:] = [nodes.reference('', date, refuri=cvs_url)] |
||||
elif name == 'content-type': |
||||
pep_type = para.astext() |
||||
uri = self.document.settings.pep_base_url + self.pep_url % 12 |
||||
para[:] = [nodes.reference('', pep_type, refuri=uri)] |
||||
elif name == 'version' and len(body): |
||||
utils.clean_rcs_keywords(para, self.rcs_keyword_substitutions) |
||||
|
||||
|
||||
class Contents(Transform): |
||||
|
||||
""" |
||||
Insert an empty table of contents topic and a transform placeholder into |
||||
the document after the RFC 2822 header. |
||||
""" |
||||
|
||||
default_priority = 380 |
||||
|
||||
def apply(self): |
||||
language = languages.get_language(self.document.settings.language_code, |
||||
self.document.reporter) |
||||
name = language.labels['contents'] |
||||
title = nodes.title('', name) |
||||
topic = nodes.topic('', title, classes=['contents']) |
||||
name = nodes.fully_normalize_name(name) |
||||
if not self.document.has_name(name): |
||||
topic['names'].append(name) |
||||
self.document.note_implicit_target(topic) |
||||
pending = nodes.pending(parts.Contents) |
||||
topic += pending |
||||
self.document.insert(1, topic) |
||||
self.document.note_pending(pending) |
||||
|
||||
|
||||
class TargetNotes(Transform): |
||||
|
||||
""" |
||||
Locate the "References" section, insert a placeholder for an external |
||||
target footnote insertion transform at the end, and schedule the |
||||
transform to run immediately. |
||||
""" |
||||
|
||||
default_priority = 520 |
||||
|
||||
def apply(self): |
||||
doc = self.document |
||||
i = len(doc) - 1 |
||||
refsect = copyright = None |
||||
while i >= 0 and isinstance(doc[i], nodes.section): |
||||
title_words = doc[i][0].astext().lower().split() |
||||
if 'references' in title_words: |
||||
refsect = doc[i] |
||||
break |
||||
elif 'copyright' in title_words: |
||||
copyright = i |
||||
i -= 1 |
||||
if not refsect: |
||||
refsect = nodes.section() |
||||
refsect += nodes.title('', 'References') |
||||
doc.set_id(refsect) |
||||
if copyright: |
||||
# Put the new "References" section before "Copyright": |
||||
doc.insert(copyright, refsect) |
||||
else: |
||||
# Put the new "References" section at end of doc: |
||||
doc.append(refsect) |
||||
pending = nodes.pending(references.TargetNotes) |
||||
refsect.append(pending) |
||||
self.document.note_pending(pending, 0) |
||||
pending = nodes.pending(misc.CallBack, |
||||
details={'callback': self.cleanup_callback}) |
||||
refsect.append(pending) |
||||
self.document.note_pending(pending, 1) |
||||
|
||||
def cleanup_callback(self, pending): |
||||
""" |
||||
Remove an empty "References" section. |
||||
|
||||
Called after the `references.TargetNotes` transform is complete. |
||||
""" |
||||
if len(pending.parent) == 2: # <title> and <pending> |
||||
pending.parent.parent.remove(pending.parent) |
||||
|
||||
|
||||
class PEPZero(Transform): |
||||
|
||||
""" |
||||
Special processing for PEP 0. |
||||
""" |
||||
|
||||
default_priority =760 |
||||
|
||||
def apply(self): |
||||
visitor = PEPZeroSpecial(self.document) |
||||
self.document.walk(visitor) |
||||
self.startnode.parent.remove(self.startnode) |
||||
|
||||
|
||||
class PEPZeroSpecial(nodes.SparseNodeVisitor): |
||||
|
||||
""" |
||||
Perform the special processing needed by PEP 0: |
||||
|
||||
- Mask email addresses. |
||||
|
||||
- Link PEP numbers in the second column of 4-column tables to the PEPs |
||||
themselves. |
||||
""" |
||||
|
||||
pep_url = Headers.pep_url |
||||
|
||||
def unknown_visit(self, node): |
||||
pass |
||||
|
||||
def visit_reference(self, node): |
||||
node.replace_self(mask_email(node)) |
||||
|
||||
def visit_field_list(self, node): |
||||
if 'rfc2822' in node['classes']: |
||||
raise nodes.SkipNode |
||||
|
||||
def visit_tgroup(self, node): |
||||
self.pep_table = node['cols'] == 4 |
||||
self.entry = 0 |
||||
|
||||
def visit_colspec(self, node): |
||||
self.entry += 1 |
||||
if self.pep_table and self.entry == 2: |
||||
node['classes'].append('num') |
||||
|
||||
def visit_row(self, node): |
||||
self.entry = 0 |
||||
|
||||
def visit_entry(self, node): |
||||
self.entry += 1 |
||||
if self.pep_table and self.entry == 2 and len(node) == 1: |
||||
node['classes'].append('num') |
||||
p = node[0] |
||||
if isinstance(p, nodes.paragraph) and len(p) == 1: |
||||
text = p.astext() |
||||
try: |
||||
pep = int(text) |
||||
ref = (self.document.settings.pep_base_url |
||||
+ self.pep_url % pep) |
||||
p[0] = nodes.reference(text, text, refuri=ref) |
||||
except ValueError: |
||||
pass |
||||
|
||||
|
||||
non_masked_addresses = ('peps@python.org', |
||||
'python-list@python.org', |
||||
'python-dev@python.org') |
||||
|
||||
def mask_email(ref, pepno=None): |
||||
""" |
||||
Mask the email address in `ref` and return a replacement node. |
||||
|
||||
`ref` is returned unchanged if it contains no email address. |
||||
|
||||
For email addresses such as "user@host", mask the address as "user at |
||||
host" (text) to thwart simple email address harvesters (except for those |
||||
listed in `non_masked_addresses`). If a PEP number (`pepno`) is given, |
||||
return a reference including a default email subject. |
||||
""" |
||||
if ref.hasattr('refuri') and ref['refuri'].startswith('mailto:'): |
||||
if ref['refuri'][8:] in non_masked_addresses: |
||||
replacement = ref[0] |
||||
else: |
||||
replacement_text = ref.astext().replace('@', ' at ') |
||||
replacement = nodes.raw('', replacement_text, format='html') |
||||
if pepno is None: |
||||
return replacement |
||||
else: |
||||
ref['refuri'] += '?subject=PEP%%20%s' % pepno |
||||
ref[:] = [replacement] |
||||
return ref |
||||
else: |
||||
return ref |
||||
@ -0,0 +1,913 @@
|
||||
# $Id: references.py 8067 2017-05-04 20:10:03Z milde $ |
||||
# Author: David Goodger <goodger@python.org> |
||||
# Copyright: This module has been placed in the public domain. |
||||
|
||||
""" |
||||
Transforms for resolving references. |
||||
""" |
||||
|
||||
__docformat__ = 'reStructuredText' |
||||
|
||||
import sys |
||||
import re |
||||
from docutils import nodes, utils |
||||
from docutils.transforms import TransformError, Transform |
||||
|
||||
|
||||
class PropagateTargets(Transform): |
||||
|
||||
""" |
||||
Propagate empty internal targets to the next element. |
||||
|
||||
Given the following nodes:: |
||||
|
||||
<target ids="internal1" names="internal1"> |
||||
<target anonymous="1" ids="id1"> |
||||
<target ids="internal2" names="internal2"> |
||||
<paragraph> |
||||
This is a test. |
||||
|
||||
PropagateTargets propagates the ids and names of the internal |
||||
targets preceding the paragraph to the paragraph itself:: |
||||
|
||||
<target refid="internal1"> |
||||
<target anonymous="1" refid="id1"> |
||||
<target refid="internal2"> |
||||
<paragraph ids="internal2 id1 internal1" names="internal2 internal1"> |
||||
This is a test. |
||||
""" |
||||
|
||||
default_priority = 260 |
||||
|
||||
def apply(self): |
||||
for target in self.document.traverse(nodes.target): |
||||
# Only block-level targets without reference (like ".. target:"): |
||||
if (isinstance(target.parent, nodes.TextElement) or |
||||
(target.hasattr('refid') or target.hasattr('refuri') or |
||||
target.hasattr('refname'))): |
||||
continue |
||||
assert len(target) == 0, 'error: block-level target has children' |
||||
next_node = target.next_node(ascend=True) |
||||
# Do not move names and ids into Invisibles (we'd lose the |
||||
# attributes) or different Targetables (e.g. footnotes). |
||||
if (next_node is not None and |
||||
((not isinstance(next_node, nodes.Invisible) and |
||||
not isinstance(next_node, nodes.Targetable)) or |
||||
isinstance(next_node, nodes.target))): |
||||
next_node['ids'].extend(target['ids']) |
||||
next_node['names'].extend(target['names']) |
||||
# Set defaults for next_node.expect_referenced_by_name/id. |
||||
if not hasattr(next_node, 'expect_referenced_by_name'): |
||||
next_node.expect_referenced_by_name = {} |
||||
if not hasattr(next_node, 'expect_referenced_by_id'): |
||||
next_node.expect_referenced_by_id = {} |
||||
for id in target['ids']: |
||||
# Update IDs to node mapping. |
||||
self.document.ids[id] = next_node |
||||
# If next_node is referenced by id ``id``, this |
||||
# target shall be marked as referenced. |
||||
next_node.expect_referenced_by_id[id] = target |
||||
for name in target['names']: |
||||
next_node.expect_referenced_by_name[name] = target |
||||
# If there are any expect_referenced_by_... attributes |
||||
# in target set, copy them to next_node. |
||||
next_node.expect_referenced_by_name.update( |
||||
getattr(target, 'expect_referenced_by_name', {})) |
||||
next_node.expect_referenced_by_id.update( |
||||
getattr(target, 'expect_referenced_by_id', {})) |
||||
# Set refid to point to the first former ID of target |
||||
# which is now an ID of next_node. |
||||
target['refid'] = target['ids'][0] |
||||
# Clear ids and names; they have been moved to |
||||
# next_node. |
||||
target['ids'] = [] |
||||
target['names'] = [] |
||||
self.document.note_refid(target) |
||||
|
||||
|
||||
class AnonymousHyperlinks(Transform): |
||||
|
||||
""" |
||||
Link anonymous references to targets. Given:: |
||||
|
||||
<paragraph> |
||||
<reference anonymous="1"> |
||||
internal |
||||
<reference anonymous="1"> |
||||
external |
||||
<target anonymous="1" ids="id1"> |
||||
<target anonymous="1" ids="id2" refuri="http://external"> |
||||
|
||||
Corresponding references are linked via "refid" or resolved via "refuri":: |
||||
|
||||
<paragraph> |
||||
<reference anonymous="1" refid="id1"> |
||||
text |
||||
<reference anonymous="1" refuri="http://external"> |
||||
external |
||||
<target anonymous="1" ids="id1"> |
||||
<target anonymous="1" ids="id2" refuri="http://external"> |
||||
""" |
||||
|
||||
default_priority = 440 |
||||
|
||||
def apply(self): |
||||
anonymous_refs = [] |
||||
anonymous_targets = [] |
||||
for node in self.document.traverse(nodes.reference): |
||||
if node.get('anonymous'): |
||||
anonymous_refs.append(node) |
||||
for node in self.document.traverse(nodes.target): |
||||
if node.get('anonymous'): |
||||
anonymous_targets.append(node) |
||||
if len(anonymous_refs) \ |
||||
!= len(anonymous_targets): |
||||
msg = self.document.reporter.error( |
||||
'Anonymous hyperlink mismatch: %s references but %s ' |
||||
'targets.\nSee "backrefs" attribute for IDs.' |
||||
% (len(anonymous_refs), len(anonymous_targets))) |
||||
msgid = self.document.set_id(msg) |
||||
for ref in anonymous_refs: |
||||
prb = nodes.problematic( |
||||
ref.rawsource, ref.rawsource, refid=msgid) |
||||
prbid = self.document.set_id(prb) |
||||
msg.add_backref(prbid) |
||||
ref.replace_self(prb) |
||||
return |
||||
for ref, target in zip(anonymous_refs, anonymous_targets): |
||||
target.referenced = 1 |
||||
while True: |
||||
if target.hasattr('refuri'): |
||||
ref['refuri'] = target['refuri'] |
||||
ref.resolved = 1 |
||||
break |
||||
else: |
||||
if not target['ids']: |
||||
# Propagated target. |
||||
target = self.document.ids[target['refid']] |
||||
continue |
||||
ref['refid'] = target['ids'][0] |
||||
self.document.note_refid(ref) |
||||
break |
||||
|
||||
|
||||
class IndirectHyperlinks(Transform): |
||||
|
||||
""" |
||||
a) Indirect external references:: |
||||
|
||||
<paragraph> |
||||
<reference refname="indirect external"> |
||||
indirect external |
||||
<target id="id1" name="direct external" |
||||
refuri="http://indirect"> |
||||
<target id="id2" name="indirect external" |
||||
refname="direct external"> |
||||
|
||||
The "refuri" attribute is migrated back to all indirect targets |
||||
from the final direct target (i.e. a target not referring to |
||||
another indirect target):: |
||||
|
||||
<paragraph> |
||||
<reference refname="indirect external"> |
||||
indirect external |
||||
<target id="id1" name="direct external" |
||||
refuri="http://indirect"> |
||||
<target id="id2" name="indirect external" |
||||
refuri="http://indirect"> |
||||
|
||||
Once the attribute is migrated, the preexisting "refname" attribute |
||||
is dropped. |
||||
|
||||
b) Indirect internal references:: |
||||
|
||||
<target id="id1" name="final target"> |
||||
<paragraph> |
||||
<reference refname="indirect internal"> |
||||
indirect internal |
||||
<target id="id2" name="indirect internal 2" |
||||
refname="final target"> |
||||
<target id="id3" name="indirect internal" |
||||
refname="indirect internal 2"> |
||||
|
||||
Targets which indirectly refer to an internal target become one-hop |
||||
indirect (their "refid" attributes are directly set to the internal |
||||
target's "id"). References which indirectly refer to an internal |
||||
target become direct internal references:: |
||||
|
||||
<target id="id1" name="final target"> |
||||
<paragraph> |
||||
<reference refid="id1"> |
||||
indirect internal |
||||
<target id="id2" name="indirect internal 2" refid="id1"> |
||||
<target id="id3" name="indirect internal" refid="id1"> |
||||
""" |
||||
|
||||
default_priority = 460 |
||||
|
||||
def apply(self): |
||||
for target in self.document.indirect_targets: |
||||
if not target.resolved: |
||||
self.resolve_indirect_target(target) |
||||
self.resolve_indirect_references(target) |
||||
|
||||
def resolve_indirect_target(self, target): |
||||
refname = target.get('refname') |
||||
if refname is None: |
||||
reftarget_id = target['refid'] |
||||
else: |
||||
reftarget_id = self.document.nameids.get(refname) |
||||
if not reftarget_id: |
||||
# Check the unknown_reference_resolvers |
||||
for resolver_function in \ |
||||
self.document.transformer.unknown_reference_resolvers: |
||||
if resolver_function(target): |
||||
break |
||||
else: |
||||
self.nonexistent_indirect_target(target) |
||||
return |
||||
reftarget = self.document.ids[reftarget_id] |
||||
reftarget.note_referenced_by(id=reftarget_id) |
||||
if isinstance(reftarget, nodes.target) \ |
||||
and not reftarget.resolved and reftarget.hasattr('refname'): |
||||
if hasattr(target, 'multiply_indirect'): |
||||
#and target.multiply_indirect): |
||||
#del target.multiply_indirect |
||||
self.circular_indirect_reference(target) |
||||
return |
||||
target.multiply_indirect = 1 |
||||
self.resolve_indirect_target(reftarget) # multiply indirect |
||||
del target.multiply_indirect |
||||
if reftarget.hasattr('refuri'): |
||||
target['refuri'] = reftarget['refuri'] |
||||
if 'refid' in target: |
||||
del target['refid'] |
||||
elif reftarget.hasattr('refid'): |
||||
target['refid'] = reftarget['refid'] |
||||
self.document.note_refid(target) |
||||
else: |
||||
if reftarget['ids']: |
||||
target['refid'] = reftarget_id |
||||
self.document.note_refid(target) |
||||
else: |
||||
self.nonexistent_indirect_target(target) |
||||
return |
||||
if refname is not None: |
||||
del target['refname'] |
||||
target.resolved = 1 |
||||
|
||||
def nonexistent_indirect_target(self, target): |
||||
if target['refname'] in self.document.nameids: |
||||
self.indirect_target_error(target, 'which is a duplicate, and ' |
||||
'cannot be used as a unique reference') |
||||
else: |
||||
self.indirect_target_error(target, 'which does not exist') |
||||
|
||||
def circular_indirect_reference(self, target): |
||||
self.indirect_target_error(target, 'forming a circular reference') |
||||
|
||||
def indirect_target_error(self, target, explanation): |
||||
naming = '' |
||||
reflist = [] |
||||
if target['names']: |
||||
naming = '"%s" ' % target['names'][0] |
||||
for name in target['names']: |
||||
reflist.extend(self.document.refnames.get(name, [])) |
||||
for id in target['ids']: |
||||
reflist.extend(self.document.refids.get(id, [])) |
||||
if target['ids']: |
||||
naming += '(id="%s")' % target['ids'][0] |
||||
msg = self.document.reporter.error( |
||||
'Indirect hyperlink target %s refers to target "%s", %s.' |
||||
% (naming, target['refname'], explanation), base_node=target) |
||||
msgid = self.document.set_id(msg) |
||||
for ref in utils.uniq(reflist): |
||||
prb = nodes.problematic( |
||||
ref.rawsource, ref.rawsource, refid=msgid) |
||||
prbid = self.document.set_id(prb) |
||||
msg.add_backref(prbid) |
||||
ref.replace_self(prb) |
||||
target.resolved = 1 |
||||
|
||||
def resolve_indirect_references(self, target): |
||||
if target.hasattr('refid'): |
||||
attname = 'refid' |
||||
call_method = self.document.note_refid |
||||
elif target.hasattr('refuri'): |
||||
attname = 'refuri' |
||||
call_method = None |
||||
else: |
||||
return |
||||
attval = target[attname] |
||||
for name in target['names']: |
||||
reflist = self.document.refnames.get(name, []) |
||||
if reflist: |
||||
target.note_referenced_by(name=name) |
||||
for ref in reflist: |
||||
if ref.resolved: |
||||
continue |
||||
del ref['refname'] |
||||
ref[attname] = attval |
||||
if call_method: |
||||
call_method(ref) |
||||
ref.resolved = 1 |
||||
if isinstance(ref, nodes.target): |
||||
self.resolve_indirect_references(ref) |
||||
for id in target['ids']: |
||||
reflist = self.document.refids.get(id, []) |
||||
if reflist: |
||||
target.note_referenced_by(id=id) |
||||
for ref in reflist: |
||||
if ref.resolved: |
||||
continue |
||||
del ref['refid'] |
||||
ref[attname] = attval |
||||
if call_method: |
||||
call_method(ref) |
||||
ref.resolved = 1 |
||||
if isinstance(ref, nodes.target): |
||||
self.resolve_indirect_references(ref) |
||||
|
||||
|
||||
class ExternalTargets(Transform): |
||||
|
||||
""" |
||||
Given:: |
||||
|
||||
<paragraph> |
||||
<reference refname="direct external"> |
||||
direct external |
||||
<target id="id1" name="direct external" refuri="http://direct"> |
||||
|
||||
The "refname" attribute is replaced by the direct "refuri" attribute:: |
||||
|
||||
<paragraph> |
||||
<reference refuri="http://direct"> |
||||
direct external |
||||
<target id="id1" name="direct external" refuri="http://direct"> |
||||
""" |
||||
|
||||
default_priority = 640 |
||||
|
||||
def apply(self): |
||||
for target in self.document.traverse(nodes.target): |
||||
if target.hasattr('refuri'): |
||||
refuri = target['refuri'] |
||||
for name in target['names']: |
||||
reflist = self.document.refnames.get(name, []) |
||||
if reflist: |
||||
target.note_referenced_by(name=name) |
||||
for ref in reflist: |
||||
if ref.resolved: |
||||
continue |
||||
del ref['refname'] |
||||
ref['refuri'] = refuri |
||||
ref.resolved = 1 |
||||
|
||||
|
||||
class InternalTargets(Transform): |
||||
|
||||
default_priority = 660 |
||||
|
||||
def apply(self): |
||||
for target in self.document.traverse(nodes.target): |
||||
if not target.hasattr('refuri') and not target.hasattr('refid'): |
||||
self.resolve_reference_ids(target) |
||||
|
||||
def resolve_reference_ids(self, target): |
||||
""" |
||||
Given:: |
||||
|
||||
<paragraph> |
||||
<reference refname="direct internal"> |
||||
direct internal |
||||
<target id="id1" name="direct internal"> |
||||
|
||||
The "refname" attribute is replaced by "refid" linking to the target's |
||||
"id":: |
||||
|
||||
<paragraph> |
||||
<reference refid="id1"> |
||||
direct internal |
||||
<target id="id1" name="direct internal"> |
||||
""" |
||||
for name in target['names']: |
||||
refid = self.document.nameids.get(name) |
||||
reflist = self.document.refnames.get(name, []) |
||||
if reflist: |
||||
target.note_referenced_by(name=name) |
||||
for ref in reflist: |
||||
if ref.resolved: |
||||
continue |
||||
if refid: |
||||
del ref['refname'] |
||||
ref['refid'] = refid |
||||
ref.resolved = 1 |
||||
|
||||
|
||||
class Footnotes(Transform): |
||||
|
||||
""" |
||||
Assign numbers to autonumbered footnotes, and resolve links to footnotes, |
||||
citations, and their references. |
||||
|
||||
Given the following ``document`` as input:: |
||||
|
||||
<document> |
||||
<paragraph> |
||||
A labeled autonumbered footnote referece: |
||||
<footnote_reference auto="1" id="id1" refname="footnote"> |
||||
<paragraph> |
||||
An unlabeled autonumbered footnote referece: |
||||
<footnote_reference auto="1" id="id2"> |
||||
<footnote auto="1" id="id3"> |
||||
<paragraph> |
||||
Unlabeled autonumbered footnote. |
||||
<footnote auto="1" id="footnote" name="footnote"> |
||||
<paragraph> |
||||
Labeled autonumbered footnote. |
||||
|
||||
Auto-numbered footnotes have attribute ``auto="1"`` and no label. |
||||
Auto-numbered footnote_references have no reference text (they're |
||||
empty elements). When resolving the numbering, a ``label`` element |
||||
is added to the beginning of the ``footnote``, and reference text |
||||
to the ``footnote_reference``. |
||||
|
||||
The transformed result will be:: |
||||
|
||||
<document> |
||||
<paragraph> |
||||
A labeled autonumbered footnote referece: |
||||
<footnote_reference auto="1" id="id1" refid="footnote"> |
||||
2 |
||||
<paragraph> |
||||
An unlabeled autonumbered footnote referece: |
||||
<footnote_reference auto="1" id="id2" refid="id3"> |
||||
1 |
||||
<footnote auto="1" id="id3" backrefs="id2"> |
||||
<label> |
||||
1 |
||||
<paragraph> |
||||
Unlabeled autonumbered footnote. |
||||
<footnote auto="1" id="footnote" name="footnote" backrefs="id1"> |
||||
<label> |
||||
2 |
||||
<paragraph> |
||||
Labeled autonumbered footnote. |
||||
|
||||
Note that the footnotes are not in the same order as the references. |
||||
|
||||
The labels and reference text are added to the auto-numbered ``footnote`` |
||||
and ``footnote_reference`` elements. Footnote elements are backlinked to |
||||
their references via "refids" attributes. References are assigned "id" |
||||
and "refid" attributes. |
||||
|
||||
After adding labels and reference text, the "auto" attributes can be |
||||
ignored. |
||||
""" |
||||
|
||||
default_priority = 620 |
||||
|
||||
autofootnote_labels = None |
||||
"""Keep track of unlabeled autonumbered footnotes.""" |
||||
|
||||
symbols = [ |
||||
# Entries 1-4 and 6 below are from section 12.51 of |
||||
# The Chicago Manual of Style, 14th edition. |
||||
'*', # asterisk/star |
||||
u'\u2020', # dagger † |
||||
u'\u2021', # double dagger ‡ |
||||
u'\u00A7', # section mark § |
||||
u'\u00B6', # paragraph mark (pilcrow) ¶ |
||||
# (parallels ['||'] in CMoS) |
||||
'#', # number sign |
||||
# The entries below were chosen arbitrarily. |
||||
u'\u2660', # spade suit ♠ |
||||
u'\u2665', # heart suit ♥ |
||||
u'\u2666', # diamond suit ♦ |
||||
u'\u2663', # club suit ♣ |
||||
] |
||||
|
||||
def apply(self): |
||||
self.autofootnote_labels = [] |
||||
startnum = self.document.autofootnote_start |
||||
self.document.autofootnote_start = self.number_footnotes(startnum) |
||||
self.number_footnote_references(startnum) |
||||
self.symbolize_footnotes() |
||||
self.resolve_footnotes_and_citations() |
||||
|
||||
def number_footnotes(self, startnum): |
||||
""" |
||||
Assign numbers to autonumbered footnotes. |
||||
|
||||
For labeled autonumbered footnotes, copy the number over to |
||||
corresponding footnote references. |
||||
""" |
||||
for footnote in self.document.autofootnotes: |
||||
while True: |
||||
label = str(startnum) |
||||
startnum += 1 |
||||
if label not in self.document.nameids: |
||||
break |
||||
footnote.insert(0, nodes.label('', label)) |
||||
for name in footnote['names']: |
||||
for ref in self.document.footnote_refs.get(name, []): |
||||
ref += nodes.Text(label) |
||||
ref.delattr('refname') |
||||
assert len(footnote['ids']) == len(ref['ids']) == 1 |
||||
ref['refid'] = footnote['ids'][0] |
||||
footnote.add_backref(ref['ids'][0]) |
||||
self.document.note_refid(ref) |
||||
ref.resolved = 1 |
||||
if not footnote['names'] and not footnote['dupnames']: |
||||
footnote['names'].append(label) |
||||
self.document.note_explicit_target(footnote, footnote) |
||||
self.autofootnote_labels.append(label) |
||||
return startnum |
||||
|
||||
def number_footnote_references(self, startnum): |
||||
"""Assign numbers to autonumbered footnote references.""" |
||||
i = 0 |
||||
for ref in self.document.autofootnote_refs: |
||||
if ref.resolved or ref.hasattr('refid'): |
||||
continue |
||||
try: |
||||
label = self.autofootnote_labels[i] |
||||
except IndexError: |
||||
msg = self.document.reporter.error( |
||||
'Too many autonumbered footnote references: only %s ' |
||||
'corresponding footnotes available.' |
||||
% len(self.autofootnote_labels), base_node=ref) |
||||
msgid = self.document.set_id(msg) |
||||
for ref in self.document.autofootnote_refs[i:]: |
||||
if ref.resolved or ref.hasattr('refname'): |
||||
continue |
||||
prb = nodes.problematic( |
||||
ref.rawsource, ref.rawsource, refid=msgid) |
||||
prbid = self.document.set_id(prb) |
||||
msg.add_backref(prbid) |
||||
ref.replace_self(prb) |
||||
break |
||||
ref += nodes.Text(label) |
||||
id = self.document.nameids[label] |
||||
footnote = self.document.ids[id] |
||||
ref['refid'] = id |
||||
self.document.note_refid(ref) |
||||
assert len(ref['ids']) == 1 |
||||
footnote.add_backref(ref['ids'][0]) |
||||
ref.resolved = 1 |
||||
i += 1 |
||||
|
||||
def symbolize_footnotes(self): |
||||
"""Add symbols indexes to "[*]"-style footnotes and references.""" |
||||
labels = [] |
||||
for footnote in self.document.symbol_footnotes: |
||||
reps, index = divmod(self.document.symbol_footnote_start, |
||||
len(self.symbols)) |
||||
labeltext = self.symbols[index] * (reps + 1) |
||||
labels.append(labeltext) |
||||
footnote.insert(0, nodes.label('', labeltext)) |
||||
self.document.symbol_footnote_start += 1 |
||||
self.document.set_id(footnote) |
||||
i = 0 |
||||
for ref in self.document.symbol_footnote_refs: |
||||
try: |
||||
ref += nodes.Text(labels[i]) |
||||
except IndexError: |
||||
msg = self.document.reporter.error( |
||||
'Too many symbol footnote references: only %s ' |
||||
'corresponding footnotes available.' % len(labels), |
||||
base_node=ref) |
||||
msgid = self.document.set_id(msg) |
||||
for ref in self.document.symbol_footnote_refs[i:]: |
||||
if ref.resolved or ref.hasattr('refid'): |
||||
continue |
||||
prb = nodes.problematic( |
||||
ref.rawsource, ref.rawsource, refid=msgid) |
||||
prbid = self.document.set_id(prb) |
||||
msg.add_backref(prbid) |
||||
ref.replace_self(prb) |
||||
break |
||||
footnote = self.document.symbol_footnotes[i] |
||||
assert len(footnote['ids']) == 1 |
||||
ref['refid'] = footnote['ids'][0] |
||||
self.document.note_refid(ref) |
||||
footnote.add_backref(ref['ids'][0]) |
||||
i += 1 |
||||
|
||||
def resolve_footnotes_and_citations(self): |
||||
""" |
||||
Link manually-labeled footnotes and citations to/from their |
||||
references. |
||||
""" |
||||
for footnote in self.document.footnotes: |
||||
for label in footnote['names']: |
||||
if label in self.document.footnote_refs: |
||||
reflist = self.document.footnote_refs[label] |
||||
self.resolve_references(footnote, reflist) |
||||
for citation in self.document.citations: |
||||
for label in citation['names']: |
||||
if label in self.document.citation_refs: |
||||
reflist = self.document.citation_refs[label] |
||||
self.resolve_references(citation, reflist) |
||||
|
||||
def resolve_references(self, note, reflist): |
||||
assert len(note['ids']) == 1 |
||||
id = note['ids'][0] |
||||
for ref in reflist: |
||||
if ref.resolved: |
||||
continue |
||||
ref.delattr('refname') |
||||
ref['refid'] = id |
||||
assert len(ref['ids']) == 1 |
||||
note.add_backref(ref['ids'][0]) |
||||
ref.resolved = 1 |
||||
note.resolved = 1 |
||||
|
||||
|
||||
class CircularSubstitutionDefinitionError(Exception): pass |
||||
|
||||
|
||||
class Substitutions(Transform): |
||||
|
||||
""" |
||||
Given the following ``document`` as input:: |
||||
|
||||
<document> |
||||
<paragraph> |
||||
The |
||||
<substitution_reference refname="biohazard"> |
||||
biohazard |
||||
symbol is deservedly scary-looking. |
||||
<substitution_definition name="biohazard"> |
||||
<image alt="biohazard" uri="biohazard.png"> |
||||
|
||||
The ``substitution_reference`` will simply be replaced by the |
||||
contents of the corresponding ``substitution_definition``. |
||||
|
||||
The transformed result will be:: |
||||
|
||||
<document> |
||||
<paragraph> |
||||
The |
||||
<image alt="biohazard" uri="biohazard.png"> |
||||
symbol is deservedly scary-looking. |
||||
<substitution_definition name="biohazard"> |
||||
<image alt="biohazard" uri="biohazard.png"> |
||||
""" |
||||
|
||||
default_priority = 220 |
||||
"""The Substitutions transform has to be applied very early, before |
||||
`docutils.tranforms.frontmatter.DocTitle` and others.""" |
||||
|
||||
def apply(self): |
||||
defs = self.document.substitution_defs |
||||
normed = self.document.substitution_names |
||||
subreflist = self.document.traverse(nodes.substitution_reference) |
||||
nested = {} |
||||
for ref in subreflist: |
||||
refname = ref['refname'] |
||||
key = None |
||||
if refname in defs: |
||||
key = refname |
||||
else: |
||||
normed_name = refname.lower() |
||||
if normed_name in normed: |
||||
key = normed[normed_name] |
||||
if key is None: |
||||
msg = self.document.reporter.error( |
||||
'Undefined substitution referenced: "%s".' |
||||
% refname, base_node=ref) |
||||
msgid = self.document.set_id(msg) |
||||
prb = nodes.problematic( |
||||
ref.rawsource, ref.rawsource, refid=msgid) |
||||
prbid = self.document.set_id(prb) |
||||
msg.add_backref(prbid) |
||||
ref.replace_self(prb) |
||||
else: |
||||
subdef = defs[key] |
||||
parent = ref.parent |
||||
index = parent.index(ref) |
||||
if ('ltrim' in subdef.attributes |
||||
or 'trim' in subdef.attributes): |
||||
if index > 0 and isinstance(parent[index - 1], |
||||
nodes.Text): |
||||
parent.replace(parent[index - 1], |
||||
parent[index - 1].rstrip()) |
||||
if ('rtrim' in subdef.attributes |
||||
or 'trim' in subdef.attributes): |
||||
if (len(parent) > index + 1 |
||||
and isinstance(parent[index + 1], nodes.Text)): |
||||
parent.replace(parent[index + 1], |
||||
parent[index + 1].lstrip()) |
||||
subdef_copy = subdef.deepcopy() |
||||
try: |
||||
# Take care of nested substitution references: |
||||
for nested_ref in subdef_copy.traverse( |
||||
nodes.substitution_reference): |
||||
nested_name = normed[nested_ref['refname'].lower()] |
||||
if nested_name in nested.setdefault(nested_name, []): |
||||
raise CircularSubstitutionDefinitionError |
||||
else: |
||||
nested[nested_name].append(key) |
||||
nested_ref['ref-origin'] = ref |
||||
subreflist.append(nested_ref) |
||||
except CircularSubstitutionDefinitionError: |
||||
parent = ref.parent |
||||
if isinstance(parent, nodes.substitution_definition): |
||||
msg = self.document.reporter.error( |
||||
'Circular substitution definition detected:', |
||||
nodes.literal_block(parent.rawsource, |
||||
parent.rawsource), |
||||
line=parent.line, base_node=parent) |
||||
parent.replace_self(msg) |
||||
else: |
||||
# find original ref substitution which cased this error |
||||
ref_origin = ref |
||||
while ref_origin.hasattr('ref-origin'): |
||||
ref_origin = ref_origin['ref-origin'] |
||||
msg = self.document.reporter.error( |
||||
'Circular substitution definition referenced: ' |
||||
'"%s".' % refname, base_node=ref_origin) |
||||
msgid = self.document.set_id(msg) |
||||
prb = nodes.problematic( |
||||
ref.rawsource, ref.rawsource, refid=msgid) |
||||
prbid = self.document.set_id(prb) |
||||
msg.add_backref(prbid) |
||||
ref.replace_self(prb) |
||||
else: |
||||
ref.replace_self(subdef_copy.children) |
||||
# register refname of the replacment node(s) |
||||
# (needed for resolution of references) |
||||
for node in subdef_copy.children: |
||||
if isinstance(node, nodes.Referential): |
||||
# HACK: verify refname attribute exists. |
||||
# Test with docs/dev/todo.txt, see. |donate| |
||||
if 'refname' in node: |
||||
self.document.note_refname(node) |
||||
|
||||
|
||||
class TargetNotes(Transform): |
||||
|
||||
""" |
||||
Creates a footnote for each external target in the text, and corresponding |
||||
footnote references after each reference. |
||||
""" |
||||
|
||||
default_priority = 540 |
||||
"""The TargetNotes transform has to be applied after `IndirectHyperlinks` |
||||
but before `Footnotes`.""" |
||||
|
||||
|
||||
def __init__(self, document, startnode): |
||||
Transform.__init__(self, document, startnode=startnode) |
||||
|
||||
self.classes = startnode.details.get('class', []) |
||||
|
||||
def apply(self): |
||||
notes = {} |
||||
nodelist = [] |
||||
for target in self.document.traverse(nodes.target): |
||||
# Only external targets. |
||||
if not target.hasattr('refuri'): |
||||
continue |
||||
names = target['names'] |
||||
refs = [] |
||||
for name in names: |
||||
refs.extend(self.document.refnames.get(name, [])) |
||||
if not refs: |
||||
continue |
||||
footnote = self.make_target_footnote(target['refuri'], refs, |
||||
notes) |
||||
if target['refuri'] not in notes: |
||||
notes[target['refuri']] = footnote |
||||
nodelist.append(footnote) |
||||
# Take care of anonymous references. |
||||
for ref in self.document.traverse(nodes.reference): |
||||
if not ref.get('anonymous'): |
||||
continue |
||||
if ref.hasattr('refuri'): |
||||
footnote = self.make_target_footnote(ref['refuri'], [ref], |
||||
notes) |
||||
if ref['refuri'] not in notes: |
||||
notes[ref['refuri']] = footnote |
||||
nodelist.append(footnote) |
||||
self.startnode.replace_self(nodelist) |
||||
|
||||
def make_target_footnote(self, refuri, refs, notes): |
||||
if refuri in notes: # duplicate? |
||||
footnote = notes[refuri] |
||||
assert len(footnote['names']) == 1 |
||||
footnote_name = footnote['names'][0] |
||||
else: # original |
||||
footnote = nodes.footnote() |
||||
footnote_id = self.document.set_id(footnote) |
||||
# Use uppercase letters and a colon; they can't be |
||||
# produced inside names by the parser. |
||||
footnote_name = 'TARGET_NOTE: ' + footnote_id |
||||
footnote['auto'] = 1 |
||||
footnote['names'] = [footnote_name] |
||||
footnote_paragraph = nodes.paragraph() |
||||
footnote_paragraph += nodes.reference('', refuri, refuri=refuri) |
||||
footnote += footnote_paragraph |
||||
self.document.note_autofootnote(footnote) |
||||
self.document.note_explicit_target(footnote, footnote) |
||||
for ref in refs: |
||||
if isinstance(ref, nodes.target): |
||||
continue |
||||
refnode = nodes.footnote_reference(refname=footnote_name, auto=1) |
||||
refnode['classes'] += self.classes |
||||
self.document.note_autofootnote_ref(refnode) |
||||
self.document.note_footnote_ref(refnode) |
||||
index = ref.parent.index(ref) + 1 |
||||
reflist = [refnode] |
||||
if not utils.get_trim_footnote_ref_space(self.document.settings): |
||||
if self.classes: |
||||
reflist.insert(0, nodes.inline(text=' ', Classes=self.classes)) |
||||
else: |
||||
reflist.insert(0, nodes.Text(' ')) |
||||
ref.parent.insert(index, reflist) |
||||
return footnote |
||||
|
||||
|
||||
class DanglingReferences(Transform): |
||||
|
||||
""" |
||||
Check for dangling references (incl. footnote & citation) and for |
||||
unreferenced targets. |
||||
""" |
||||
|
||||
default_priority = 850 |
||||
|
||||
def apply(self): |
||||
visitor = DanglingReferencesVisitor( |
||||
self.document, |
||||
self.document.transformer.unknown_reference_resolvers) |
||||
self.document.walk(visitor) |
||||
# *After* resolving all references, check for unreferenced |
||||
# targets: |
||||
for target in self.document.traverse(nodes.target): |
||||
if not target.referenced: |
||||
if target.get('anonymous'): |
||||
# If we have unreferenced anonymous targets, there |
||||
# is already an error message about anonymous |
||||
# hyperlink mismatch; no need to generate another |
||||
# message. |
||||
continue |
||||
if target['names']: |
||||
naming = target['names'][0] |
||||
elif target['ids']: |
||||
naming = target['ids'][0] |
||||
else: |
||||
# Hack: Propagated targets always have their refid |
||||
# attribute set. |
||||
naming = target['refid'] |
||||
self.document.reporter.info( |
||||
'Hyperlink target "%s" is not referenced.' |
||||
% naming, base_node=target) |
||||
|
||||
|
||||
class DanglingReferencesVisitor(nodes.SparseNodeVisitor): |
||||
|
||||
def __init__(self, document, unknown_reference_resolvers): |
||||
nodes.SparseNodeVisitor.__init__(self, document) |
||||
self.document = document |
||||
self.unknown_reference_resolvers = unknown_reference_resolvers |
||||
|
||||
def unknown_visit(self, node): |
||||
pass |
||||
|
||||
def visit_reference(self, node): |
||||
if node.resolved or not node.hasattr('refname'): |
||||
return |
||||
refname = node['refname'] |
||||
id = self.document.nameids.get(refname) |
||||
if id is None: |
||||
for resolver_function in self.unknown_reference_resolvers: |
||||
if resolver_function(node): |
||||
break |
||||
else: |
||||
if refname in self.document.nameids: |
||||
msg = self.document.reporter.error( |
||||
'Duplicate target name, cannot be used as a unique ' |
||||
'reference: "%s".' % (node['refname']), base_node=node) |
||||
else: |
||||
msg = self.document.reporter.error( |
||||
'Unknown target name: "%s".' % (node['refname']), |
||||
base_node=node) |
||||
msgid = self.document.set_id(msg) |
||||
prb = nodes.problematic( |
||||
node.rawsource, node.rawsource, refid=msgid) |
||||
try: |
||||
prbid = node['ids'][0] |
||||
except IndexError: |
||||
prbid = self.document.set_id(prb) |
||||
msg.add_backref(prbid) |
||||
node.replace_self(prb) |
||||
else: |
||||
del node['refname'] |
||||
node['refid'] = id |
||||
self.document.ids[id].note_referenced_by(id=id) |
||||
node.resolved = 1 |
||||
|
||||
visit_footnote_reference = visit_citation_reference = visit_reference |
||||
@ -0,0 +1,311 @@
|
||||
# $Id: universal.py 8144 2017-07-26 21:25:08Z milde $ |
||||
# -*- coding: utf-8 -*- |
||||
# Authors: David Goodger <goodger@python.org>; Ueli Schlaepfer; Günter Milde |
||||
# Maintainer: docutils-develop@lists.sourceforge.net |
||||
# Copyright: This module has been placed in the public domain. |
||||
|
||||
""" |
||||
Transforms needed by most or all documents: |
||||
|
||||
- `Decorations`: Generate a document's header & footer. |
||||
- `Messages`: Placement of system messages stored in |
||||
`nodes.document.transform_messages`. |
||||
- `TestMessages`: Like `Messages`, used on test runs. |
||||
- `FinalReferences`: Resolve remaining references. |
||||
""" |
||||
|
||||
__docformat__ = 'reStructuredText' |
||||
|
||||
import re |
||||
import sys |
||||
import time |
||||
from docutils import nodes, utils |
||||
from docutils.transforms import TransformError, Transform |
||||
from docutils.utils import smartquotes |
||||
|
||||
class Decorations(Transform): |
||||
|
||||
""" |
||||
Populate a document's decoration element (header, footer). |
||||
""" |
||||
|
||||
default_priority = 820 |
||||
|
||||
def apply(self): |
||||
header_nodes = self.generate_header() |
||||
if header_nodes: |
||||
decoration = self.document.get_decoration() |
||||
header = decoration.get_header() |
||||
header.extend(header_nodes) |
||||
footer_nodes = self.generate_footer() |
||||
if footer_nodes: |
||||
decoration = self.document.get_decoration() |
||||
footer = decoration.get_footer() |
||||
footer.extend(footer_nodes) |
||||
|
||||
def generate_header(self): |
||||
return None |
||||
|
||||
def generate_footer(self): |
||||
# @@@ Text is hard-coded for now. |
||||
# Should be made dynamic (language-dependent). |
||||
# @@@ Use timestamp from the `SOURCE_DATE_EPOCH`_ environment variable |
||||
# for the datestamp? |
||||
# See https://sourceforge.net/p/docutils/patches/132/ |
||||
# and https://reproducible-builds.org/specs/source-date-epoch/ |
||||
settings = self.document.settings |
||||
if settings.generator or settings.datestamp or settings.source_link \ |
||||
or settings.source_url: |
||||
text = [] |
||||
if settings.source_link and settings._source \ |
||||
or settings.source_url: |
||||
if settings.source_url: |
||||
source = settings.source_url |
||||
else: |
||||
source = utils.relative_path(settings._destination, |
||||
settings._source) |
||||
text.extend([ |
||||
nodes.reference('', 'View document source', |
||||
refuri=source), |
||||
nodes.Text('.\n')]) |
||||
if settings.datestamp: |
||||
datestamp = time.strftime(settings.datestamp, time.gmtime()) |
||||
text.append(nodes.Text('Generated on: ' + datestamp + '.\n')) |
||||
if settings.generator: |
||||
text.extend([ |
||||
nodes.Text('Generated by '), |
||||
nodes.reference('', 'Docutils', refuri= |
||||
'http://docutils.sourceforge.net/'), |
||||
nodes.Text(' from '), |
||||
nodes.reference('', 'reStructuredText', refuri='http://' |
||||
'docutils.sourceforge.net/rst.html'), |
||||
nodes.Text(' source.\n')]) |
||||
return [nodes.paragraph('', '', *text)] |
||||
else: |
||||
return None |
||||
|
||||
|
||||
class ExposeInternals(Transform): |
||||
|
||||
""" |
||||
Expose internal attributes if ``expose_internals`` setting is set. |
||||
""" |
||||
|
||||
default_priority = 840 |
||||
|
||||
def not_Text(self, node): |
||||
return not isinstance(node, nodes.Text) |
||||
|
||||
def apply(self): |
||||
if self.document.settings.expose_internals: |
||||
for node in self.document.traverse(self.not_Text): |
||||
for att in self.document.settings.expose_internals: |
||||
value = getattr(node, att, None) |
||||
if value is not None: |
||||
node['internal:' + att] = value |
||||
|
||||
|
||||
class Messages(Transform): |
||||
|
||||
""" |
||||
Place any system messages generated after parsing into a dedicated section |
||||
of the document. |
||||
""" |
||||
|
||||
default_priority = 860 |
||||
|
||||
def apply(self): |
||||
unfiltered = self.document.transform_messages |
||||
threshold = self.document.reporter.report_level |
||||
messages = [] |
||||
for msg in unfiltered: |
||||
if msg['level'] >= threshold and not msg.parent: |
||||
messages.append(msg) |
||||
if messages: |
||||
section = nodes.section(classes=['system-messages']) |
||||
# @@@ get this from the language module? |
||||
section += nodes.title('', 'Docutils System Messages') |
||||
section += messages |
||||
self.document.transform_messages[:] = [] |
||||
self.document += section |
||||
|
||||
|
||||
class FilterMessages(Transform): |
||||
|
||||
""" |
||||
Remove system messages below verbosity threshold. |
||||
""" |
||||
|
||||
default_priority = 870 |
||||
|
||||
def apply(self): |
||||
for node in self.document.traverse(nodes.system_message): |
||||
if node['level'] < self.document.reporter.report_level: |
||||
node.parent.remove(node) |
||||
|
||||
|
||||
class TestMessages(Transform): |
||||
|
||||
""" |
||||
Append all post-parse system messages to the end of the document. |
||||
|
||||
Used for testing purposes. |
||||
""" |
||||
|
||||
default_priority = 880 |
||||
|
||||
def apply(self): |
||||
for msg in self.document.transform_messages: |
||||
if not msg.parent: |
||||
self.document += msg |
||||
|
||||
|
||||
class StripComments(Transform): |
||||
|
||||
""" |
||||
Remove comment elements from the document tree (only if the |
||||
``strip_comments`` setting is enabled). |
||||
""" |
||||
|
||||
default_priority = 740 |
||||
|
||||
def apply(self): |
||||
if self.document.settings.strip_comments: |
||||
for node in self.document.traverse(nodes.comment): |
||||
node.parent.remove(node) |
||||
|
||||
|
||||
class StripClassesAndElements(Transform): |
||||
|
||||
""" |
||||
Remove from the document tree all elements with classes in |
||||
`self.document.settings.strip_elements_with_classes` and all "classes" |
||||
attribute values in `self.document.settings.strip_classes`. |
||||
""" |
||||
|
||||
default_priority = 420 |
||||
|
||||
def apply(self): |
||||
if not (self.document.settings.strip_elements_with_classes |
||||
or self.document.settings.strip_classes): |
||||
return |
||||
# prepare dicts for lookup (not sets, for Python 2.2 compatibility): |
||||
self.strip_elements = dict( |
||||
[(key, None) |
||||
for key in (self.document.settings.strip_elements_with_classes |
||||
or [])]) |
||||
self.strip_classes = dict( |
||||
[(key, None) for key in (self.document.settings.strip_classes |
||||
or [])]) |
||||
for node in self.document.traverse(self.check_classes): |
||||
node.parent.remove(node) |
||||
|
||||
def check_classes(self, node): |
||||
if isinstance(node, nodes.Element): |
||||
for class_value in node['classes'][:]: |
||||
if class_value in self.strip_classes: |
||||
node['classes'].remove(class_value) |
||||
if class_value in self.strip_elements: |
||||
return 1 |
||||
|
||||
|
||||
class SmartQuotes(Transform): |
||||
|
||||
""" |
||||
Replace ASCII quotation marks with typographic form. |
||||
|
||||
Also replace multiple dashes with em-dash/en-dash characters. |
||||
""" |
||||
|
||||
default_priority = 850 |
||||
|
||||
nodes_to_skip = (nodes.FixedTextElement, nodes.Special) |
||||
"""Do not apply "smartquotes" to instances of these block-level nodes.""" |
||||
|
||||
literal_nodes = (nodes.image, nodes.literal, nodes.math, |
||||
nodes.raw, nodes.problematic) |
||||
"""Do not change quotes in instances of these inline nodes.""" |
||||
|
||||
smartquotes_action = 'qDe' |
||||
"""Setting to select smartquote transformations. |
||||
|
||||
The default 'qDe' educates normal quote characters: (", '), |
||||
em- and en-dashes (---, --) and ellipses (...). |
||||
""" |
||||
|
||||
def __init__(self, document, startnode): |
||||
Transform.__init__(self, document, startnode=startnode) |
||||
self.unsupported_languages = set() |
||||
|
||||
def get_tokens(self, txtnodes): |
||||
# A generator that yields ``(texttype, nodetext)`` tuples for a list |
||||
# of "Text" nodes (interface to ``smartquotes.educate_tokens()``). |
||||
|
||||
texttype = {True: 'literal', # "literal" text is not changed: |
||||
False: 'plain'} |
||||
for txtnode in txtnodes: |
||||
nodetype = texttype[isinstance(txtnode.parent, |
||||
self.literal_nodes)] |
||||
yield (nodetype, txtnode.astext()) |
||||
|
||||
|
||||
def apply(self): |
||||
smart_quotes = self.document.settings.smart_quotes |
||||
if not smart_quotes: |
||||
return |
||||
try: |
||||
alternative = smart_quotes.startswith('alt') |
||||
except AttributeError: |
||||
alternative = False |
||||
# print repr(alternative) |
||||
|
||||
document_language = self.document.settings.language_code |
||||
lc_smartquotes = self.document.settings.smartquotes_locales |
||||
if lc_smartquotes: |
||||
smartquotes.smartchars.quotes.update(dict(lc_smartquotes)) |
||||
|
||||
# "Educate" quotes in normal text. Handle each block of text |
||||
# (TextElement node) as a unit to keep context around inline nodes: |
||||
for node in self.document.traverse(nodes.TextElement): |
||||
# skip preformatted text blocks and special elements: |
||||
if isinstance(node, self.nodes_to_skip): |
||||
continue |
||||
# nested TextElements are not "block-level" elements: |
||||
if isinstance(node.parent, nodes.TextElement): |
||||
continue |
||||
|
||||
# list of text nodes in the "text block": |
||||
txtnodes = [txtnode for txtnode in node.traverse(nodes.Text) |
||||
if not isinstance(txtnode.parent, |
||||
nodes.option_string)] |
||||
|
||||
# language: use typographical quotes for language "lang" |
||||
lang = node.get_language_code(document_language) |
||||
# use alternative form if `smart-quotes` setting starts with "alt": |
||||
if alternative: |
||||
if '-x-altquot' in lang: |
||||
lang = lang.replace('-x-altquot', '') |
||||
else: |
||||
lang += '-x-altquot' |
||||
# drop unsupported subtags: |
||||
for tag in utils.normalize_language_tag(lang): |
||||
if tag in smartquotes.smartchars.quotes: |
||||
lang = tag |
||||
break |
||||
else: # language not supported: (keep ASCII quotes) |
||||
if lang not in self.unsupported_languages: |
||||
self.document.reporter.warning('No smart quotes ' |
||||
'defined for language "%s".'%lang, base_node=node) |
||||
self.unsupported_languages.add(lang) |
||||
lang = '' |
||||
|
||||
# Iterator educating quotes in plain text: |
||||
# (see "utils/smartquotes.py" for the attribute setting) |
||||
teacher = smartquotes.educate_tokens(self.get_tokens(txtnodes), |
||||
attr=self.smartquotes_action, language=lang) |
||||
|
||||
for txtnode, newtext in zip(txtnodes, teacher): |
||||
txtnode.parent.replace(txtnode, nodes.Text(newtext, |
||||
rawsource=txtnode.rawsource)) |
||||
|
||||
self.unsupported_languages = set() # reset |
||||
@ -0,0 +1,88 @@
|
||||
# $Id: writer_aux.py 7808 2015-02-27 17:03:32Z milde $ |
||||
# Author: Lea Wiemann <LeWiemann@gmail.com> |
||||
# Copyright: This module has been placed in the public domain. |
||||
|
||||
""" |
||||
Auxiliary transforms mainly to be used by Writer components. |
||||
|
||||
This module is called "writer_aux" because otherwise there would be |
||||
conflicting imports like this one:: |
||||
|
||||
from docutils import writers |
||||
from docutils.transforms import writers |
||||
""" |
||||
|
||||
__docformat__ = 'reStructuredText' |
||||
|
||||
from docutils import nodes, utils, languages |
||||
from docutils.transforms import Transform |
||||
|
||||
|
||||
class Compound(Transform): |
||||
|
||||
""" |
||||
Flatten all compound paragraphs. For example, transform :: |
||||
|
||||
<compound> |
||||
<paragraph> |
||||
<literal_block> |
||||
<paragraph> |
||||
|
||||
into :: |
||||
|
||||
<paragraph> |
||||
<literal_block classes="continued"> |
||||
<paragraph classes="continued"> |
||||
""" |
||||
|
||||
default_priority = 910 |
||||
|
||||
def apply(self): |
||||
for compound in self.document.traverse(nodes.compound): |
||||
first_child = True |
||||
for child in compound: |
||||
if first_child: |
||||
if not isinstance(child, nodes.Invisible): |
||||
first_child = False |
||||
else: |
||||
child['classes'].append('continued') |
||||
# Substitute children for compound. |
||||
compound.replace_self(compound[:]) |
||||
|
||||
|
||||
class Admonitions(Transform): |
||||
|
||||
""" |
||||
Transform specific admonitions, like this: |
||||
|
||||
<note> |
||||
<paragraph> |
||||
Note contents ... |
||||
|
||||
into generic admonitions, like this:: |
||||
|
||||
<admonition classes="note"> |
||||
<title> |
||||
Note |
||||
<paragraph> |
||||
Note contents ... |
||||
|
||||
The admonition title is localized. |
||||
""" |
||||
|
||||
default_priority = 920 |
||||
|
||||
def apply(self): |
||||
language = languages.get_language(self.document.settings.language_code, |
||||
self.document.reporter) |
||||
for node in self.document.traverse(nodes.Admonition): |
||||
node_name = node.__class__.__name__ |
||||
# Set class, so that we know what node this admonition came from. |
||||
node['classes'].append(node_name) |
||||
if not isinstance(node, nodes.admonition): |
||||
# Specific admonition. Transform into a generic admonition. |
||||
admonition = nodes.admonition(node.rawsource, *node.children, |
||||
**node.attributes) |
||||
title = nodes.title('', language.labels[node_name]) |
||||
admonition.insert(0, title) |
||||
node.replace_self(admonition) |
||||
Loading…
Reference in new issue