From 7d4ce97ec3d7434aea6282741534a3c4d94fb975 Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Tue, 17 Jun 2008 10:06:37 +0000
Subject: [PATCH] Add default_role configuration value.

---
 CHANGES               |  3 +++
 TODO                  |  6 ++----
 doc/config.rst        | 12 ++++++++++++
 doc/markup/inline.rst |  7 +++++++
 sphinx/config.py      |  1 +
 sphinx/environment.py | 14 +++++++++++++-
 sphinx/quickstart.py  |  3 +++
 sphinx/roles.py       |  8 ++++++--
 8 files changed, 47 insertions(+), 7 deletions(-)

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 <ul>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,