Add the "oldcmarkup" extension, to help migrating to 1.0.

doc/domains.rst

@@ -367,6 +367,8 @@ A similar heuristic is used to determine whether the name is an attribute of the
 currently documented class.
 
 
+.. _c-domain:
+
 The C Domain
 ------------
 

doc/ext/oldcmarkup.rst

@@ -0,0 +1,35 @@
+:mod:`sphinx.ext.oldcmarkup` -- Compatibility extension for old C markup
+========================================================================
+
+.. module:: sphinx.ext.oldcmarkup
+   :synopsis: Allow further use of the pre-domain C markup
+.. moduleauthor:: Georg Brandl
+
+.. versionadded:: 1.0
+
+
+This extension is a transition helper for projects that used the old
+(pre-domain) C markup, i.e. the directives like ``cfunction`` and roles like
+``cfunc``.  Since the introduction of domains, they must be called by their
+fully-qualified name (``c:function`` and ``c:func``, respectively) or, with the
+default domain set to ``c``, by their new name (``function`` and ``func``).
+(See :ref:`c-domain` for the details.)
+
+If you activate this extension, it will register the old names, and you can
+use them like before Sphinx 1.0.  The directives are:
+
+- ``cfunction``
+- ``cmember``
+- ``cmacro``
+- ``ctype``
+- ``cvar``
+
+The roles are:
+
+- ``cdata``
+- ``cfunc``
+- ``cmacro``
+- ``ctype``
+
+However, it is advised to migrate to the new markup -- this extension is a
+compatibility convenience and will disappear in a future version of Sphinx.

doc/extensions.rst

@@ -53,6 +53,7 @@ These extensions are built in and can be activated by respective entries in the
    ext/todo
    ext/extlinks
    ext/viewcode
+   ext/oldcmarkup
 
 
 Third-party extensions

sphinx/ext/oldcmarkup.py

@@ -0,0 +1,52 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.ext.oldcmarkup
+    ~~~~~~~~~~~~~~~~~~~~~
+
+    Extension for compatibility with old C markup (directives and roles).
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from docutils.parsers.rst import directives
+
+from sphinx.util.compat import Directive
+
+
+class OldCDirective(Directive):
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {
+        'noindex': directives.flag,
+        'module': directives.unchanged,
+    }
+
+    def run(self):
+        env = self.state.document.settings.env
+        newname = 'c:' + self.name[1:]
+        newdir = env.lookup_domain_element('directive', newname)[0]
+        return newdir(newname, self.arguments, self.options,
+                      self.content, self.lineno, self.content_offset,
+                      self.block_text, self.state, self.state_machine).run()
+
+
+def old_crole(typ, rawtext, text, lineno, inliner, options={}, content=[]):
+    env = inliner.document.settings.env
+    newtyp = 'c:' + typ[1:]
+    newrole = env.lookup_domain_element('role', newtyp)[0]
+    return newrole(newtyp, rawtext, text, lineno, inliner, options, content)
+
+
+def setup(app):
+    app.add_directive('cfunction', OldCDirective)
+    app.add_directive('cmember', OldCDirective)
+    app.add_directive('cmacro', OldCDirective)
+    app.add_directive('ctype', OldCDirective)
+    app.add_directive('cvar', OldCDirective)
+    app.add_role('cdata', old_crole)
+    app.add_role('cfunc', old_crole)
+    app.add_role('cmacro', old_crole)
+    app.add_role('ctype', old_crole)

tests/root/conf.py

@@ -6,7 +6,8 @@ sys.path.append(os.path.abspath('.'))
 
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.jsmath', 'sphinx.ext.todo',
               'sphinx.ext.coverage', 'sphinx.ext.autosummary',
-              'sphinx.ext.doctest', 'sphinx.ext.extlinks', 'ext']
+              'sphinx.ext.doctest', 'sphinx.ext.extlinks',
+              'sphinx.ext.oldcmarkup', 'ext']
 
 jsmath_path = 'dummy.js'
 

tests/root/objects.txt

@@ -73,6 +73,14 @@ C items
 .. c:var:: sphinx_global
 
 
+Old C items (from oldcmarkup ext)
+---------------------------------
+
+.. cfunction:: Sphinx_Func()
+
+Refer to :cfunc:`Sphinx_Func`.
+
+
 Javascript items
 ================
 

tests/test_build_html.py

@@ -157,6 +157,8 @@ HTML_XPATH = {
         ".//a[@href='#SPHINX_USE_PYTHON']": '',
         ".//a[@href='#SphinxType']": '',
         ".//a[@href='#sphinx_global']": '',
+        # reference from old C markup extension
+        ".//a[@href='#Sphinx_Func']": '',
         # test global TOC created by toctree()
         ".//ul[@class='current']/li[@class='toctree-l1 current']/a[@href='']":
             'Testing object descriptions',