[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

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,
