1. Georg Brandl
  2. sphinx


georg.brandl  committed 90e6d06

Add default_role configuration value.

  • Participants
  • Parent commits c6fa4b3
  • Branches default

Comments (0)

Files changed (8)


View file
 * ``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


View file
-Global TODO
+Sphinx TODO
+- remove redundant <ul>s in tocs
 - autoattribute in autodoc
 - range and object options for literalinclude
 - option for compact module index

File doc/config.rst

View file
    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

File doc/markup/inline.rst

View file
    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,

File sphinx/config.py

View file
         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),

File sphinx/environment.py

View file
 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
+dummy_reporter = Reporter('', 4, 4)
 class RedirStream(object):
     def __init__(self, writefunc):
         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,
         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):

File sphinx/quickstart.py

View file
 # 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

File sphinx/roles.py

View file
 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
 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] == '!':
             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
     'const': xfileref_role,
     'attr': xfileref_role,
     'meth': xfileref_role,
+    'obj': xfileref_role,
     'cfunc' : xfileref_role,
     'cdata' : xfileref_role,
     'ctype' : xfileref_role,