[Python-checkins] r64333 - in doctools/trunk: CHANGES TODO doc/config.rst doc/markup/inline.rst sphinx/config.py sphinx/environment.py sphinx/quickstart.py sphinx/roles.py
georg.brandl
python-checkins at python.org
Tue Jun 17 12:06:39 CEST 2008
Author: georg.brandl
Date: Tue Jun 17 12:06:37 2008
New Revision: 64333
Log:
Add default_role configuration value.
Modified:
doctools/trunk/CHANGES
doctools/trunk/TODO
doctools/trunk/doc/config.rst
doctools/trunk/doc/markup/inline.rst
doctools/trunk/sphinx/config.py
doctools/trunk/sphinx/environment.py
doctools/trunk/sphinx/quickstart.py
doctools/trunk/sphinx/roles.py
Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES (original)
+++ doctools/trunk/CHANGES Tue Jun 17 12:06:37 2008
@@ -7,6 +7,9 @@
* ``tocdepth`` can be given as a file-wide metadata entry, and
specifies the maximum depth of a TOC of this file.
+* The new config value `default_role` can be used to select the
+ default role for all documents.
+
* HTML output:
- The "previous" and "next" links have a more logical structure, so
Modified: doctools/trunk/TODO
==============================================================================
--- doctools/trunk/TODO (original)
+++ doctools/trunk/TODO Tue Jun 17 12:06:37 2008
@@ -1,9 +1,7 @@
-Global TODO
+Sphinx TODO
===========
-Sphinx
-******
-
+- remove redundant <ul>s in tocs
- autoattribute in autodoc
- range and object options for literalinclude
- option for compact module index
Modified: doctools/trunk/doc/config.rst
==============================================================================
--- doctools/trunk/doc/config.rst (original)
+++ doctools/trunk/doc/config.rst Tue Jun 17 12:06:37 2008
@@ -153,6 +153,18 @@
instance is then used to render HTML documents, and possibly the output of
other builders (currently the changes builder).
+.. confval:: default_role
+
+ The name of a reST role (builtin or Sphinx extension) to use as the default
+ role, that is, for text marked up ```like this```. This can be set to
+ ``'obj'`` to make ```filter``` a cross-reference to the function "filter".
+ The default is ``None``, which doesn't reassign the default role.
+
+ The default role can always be set within individual documents using the
+ standard reST :dir:`default-role` directive.
+
+ .. versionadded:: 0.4
+
.. confval:: add_function_parentheses
A boolean that decides whether parentheses are appended to function and
Modified: doctools/trunk/doc/markup/inline.rst
==============================================================================
--- doctools/trunk/doc/markup/inline.rst (original)
+++ doctools/trunk/doc/markup/inline.rst Tue Jun 17 12:06:37 2008
@@ -88,6 +88,13 @@
The name of an exception. A dotted name may be used.
+.. role:: obj
+
+ The name of an object of unspecified type. Useful e.g. as the
+ :confval:`default_role`.
+
+ .. versionadded:: 0.4
+
The name enclosed in this markup can include a module name and/or a class name.
For example, ``:func:`filter``` could refer to a function named ``filter`` in
the current module, or the built-in function of that name. In contrast,
Modified: doctools/trunk/sphinx/config.py
==============================================================================
--- doctools/trunk/sphinx/config.py (original)
+++ doctools/trunk/sphinx/config.py Tue Jun 17 12:06:37 2008
@@ -36,6 +36,7 @@
unused_docs = ([], True),
exclude_dirs = ([], True),
exclude_trees = ([], True),
+ default_role = (None, True),
add_function_parentheses = (True, True),
add_module_names = (True, True),
show_authors = (False, True),
Modified: doctools/trunk/sphinx/environment.py
==============================================================================
--- doctools/trunk/sphinx/environment.py (original)
+++ doctools/trunk/sphinx/environment.py Tue Jun 17 12:06:37 2008
@@ -34,6 +34,8 @@
from docutils.core import publish_doctree
from docutils.utils import Reporter
from docutils.readers import standalone
+from docutils.parsers.rst import roles
+from docutils.parsers.rst.languages import en as english
from docutils.transforms import Transform
from docutils.transforms.parts import ContentsFilter
from docutils.transforms.universal import FilterMessages
@@ -70,6 +72,8 @@
'today',
])
+dummy_reporter = Reporter('', 4, 4)
+
class RedirStream(object):
def __init__(self, writefunc):
@@ -449,6 +453,14 @@
if src_path is None:
src_path = self.doc2path(docname)
+ if self.config.default_role:
+ role_fn, messages = roles.role(self.config.default_role, english,
+ 0, dummy_reporter)
+ if role_fn:
+ roles._roles[''] = role_fn
+ else:
+ self.warn(docname, 'default role %s not found' %
+ self.config.default_role)
self.docname = docname
doctree = publish_doctree(None, src_path, FileInput,
settings_overrides=self.settings,
@@ -834,7 +846,7 @@
return newnode
descroles = frozenset(('data', 'exc', 'func', 'class', 'const', 'attr',
- 'meth', 'cfunc', 'cdata', 'ctype', 'cmacro'))
+ 'meth', 'cfunc', 'cdata', 'ctype', 'cmacro', 'obj'))
def resolve_references(self, doctree, fromdocname, builder):
for node in doctree.traverse(addnodes.pending_xref):
Modified: doctools/trunk/sphinx/quickstart.py
==============================================================================
--- doctools/trunk/sphinx/quickstart.py (original)
+++ doctools/trunk/sphinx/quickstart.py Tue Jun 17 12:06:37 2008
@@ -78,6 +78,9 @@
# for source files.
#exclude_dirs = []
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
Modified: doctools/trunk/sphinx/roles.py
==============================================================================
--- doctools/trunk/sphinx/roles.py (original)
+++ doctools/trunk/sphinx/roles.py Tue Jun 17 12:06:37 2008
@@ -39,6 +39,8 @@
def indexmarkup_role(typ, rawtext, etext, lineno, inliner, options={}, content=[]):
env = inliner.document.settings.env
+ if not typ:
+ typ = env.config.default_role
text = utils.unescape(etext)
targetid = 'index-%s' % env.index_num
env.index_num += 1
@@ -114,6 +116,8 @@
def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
env = inliner.document.settings.env
+ if not typ:
+ typ = env.config.default_role
text = utils.unescape(text)
# if the first character is a bang, don't cross-reference at all
if text[0:1] == '!':
@@ -142,7 +146,7 @@
target = text[brace+1:]
title = text[:brace]
# special target for Python object cross-references
- if typ in ('data', 'exc', 'func', 'class', 'const', 'attr', 'meth', 'mod'):
+ if typ in ('data', 'exc', 'func', 'class', 'const', 'attr', 'meth', 'mod', 'obj'):
# fix-up parentheses in link title
if titleistarget:
title = title.lstrip('.') # only has a meaning for the target
@@ -209,7 +213,7 @@
'const': xfileref_role,
'attr': xfileref_role,
'meth': xfileref_role,
-
+ 'obj': xfileref_role,
'cfunc' : xfileref_role,
'cdata' : xfileref_role,
'ctype' : xfileref_role,
More information about the Python-checkins
mailing list