diff --git a/CHANGES b/CHANGES
index 566660982..b206d5c45 100644
--- a/CHANGES
+++ b/CHANGES
@@ -7,6 +7,9 @@ New features added
* ``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
diff --git a/TODO b/TODO
index 910563bcd..619c21230 100644
--- a/TODO
+++ b/TODO
@@ -1,9 +1,7 @@
-Global TODO
+Sphinx TODO
===========
-Sphinx
-******
-
+- remove redundant
s in tocs
- autoattribute in autodoc
- range and object options for literalinclude
- option for compact module index
diff --git a/doc/config.rst b/doc/config.rst
index 2cbe850c1..b0db6c86e 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -153,6 +153,18 @@ General configuration
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
diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst
index 6b636f928..724517f1e 100644
--- a/doc/markup/inline.rst
+++ b/doc/markup/inline.rst
@@ -88,6 +88,13 @@ a matching identifier is found:
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,
diff --git a/sphinx/config.py b/sphinx/config.py
index fde87173b..27dd0c9ec 100644
--- a/sphinx/config.py
+++ b/sphinx/config.py
@@ -36,6 +36,7 @@ class Config(object):
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),
diff --git a/sphinx/environment.py b/sphinx/environment.py
index eacc8f96d..d9b3cf886 100644
--- a/sphinx/environment.py
+++ b/sphinx/environment.py
@@ -34,6 +34,8 @@ from docutils.io import FileInput
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 @@ default_substitutions = set([
'today',
])
+dummy_reporter = Reporter('', 4, 4)
+
class RedirStream(object):
def __init__(self, writefunc):
@@ -449,6 +453,14 @@ class BuildEnvironment:
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 @@ class BuildEnvironment:
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):
diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py
index 2df7fabbb..0831cd967 100644
--- a/sphinx/quickstart.py
+++ b/sphinx/quickstart.py
@@ -78,6 +78,9 @@ today_fmt = '%%B %%d, %%Y'
# 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
diff --git a/sphinx/roles.py b/sphinx/roles.py
index 93eb384ab..d7ff843ef 100644
--- a/sphinx/roles.py
+++ b/sphinx/roles.py
@@ -39,6 +39,8 @@ for rolename, nodeclass in generic_docroles.iteritems():
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 _fix_parens(typ, text, env):
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 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
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 @@ specific_docroles = {
'const': xfileref_role,
'attr': xfileref_role,
'meth': xfileref_role,
-
+ 'obj': xfileref_role,
'cfunc' : xfileref_role,
'cdata' : xfileref_role,
'ctype' : xfileref_role,