diff --git a/CHANGES b/CHANGES index 4be9eed820..fb5d0b3c70 100644 --- a/CHANGES +++ b/CHANGES @@ -15,9 +15,10 @@ Incompatible changes - JavaScript - reStructuredText -* The old markup for defining and linking to C directives will not work - anymore without activating the :mod:`~sphinx.ext.oldcmarkup` - extension. +* The old markup for defining and linking to C directives is now + deprecated. It will not work anymore in future versions without + activating the :mod:`~sphinx.ext.oldcmarkup` extension; in Sphinx + 1.0, it is activated by default. * Removed support for old dependency versions; requirements are now: diff --git a/sphinx/application.py b/sphinx/application.py index 3ffd86c26e..97778d3fba 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -109,7 +109,9 @@ class Sphinx(object): if self.confdir is None: self.confdir = self.srcdir - # load all extension modules + # backwards compatibility: activate old C markup + self.setup_extension('sphinx.ext.oldcmarkup') + # load all user-given extension modules for extension in self.config.extensions: self.setup_extension(extension) # the config file itself can be an extension diff --git a/sphinx/ext/oldcmarkup.py b/sphinx/ext/oldcmarkup.py index 62f5ee28d3..c2172b088a 100644 --- a/sphinx/ext/oldcmarkup.py +++ b/sphinx/ext/oldcmarkup.py @@ -13,6 +13,10 @@ from docutils.parsers.rst import directives from sphinx.util.compat import Directive +_warned_oldcmarkup = False +WARNING_MSG = 'using old C markup; please migrate to new-style markup ' \ + '(e.g. c:function instead of cfunction), see ' \ + 'http://sphinx.pocoo.org/domains.html' class OldCDirective(Directive): has_content = True @@ -26,6 +30,9 @@ class OldCDirective(Directive): def run(self): env = self.state.document.settings.env + if not env.app._oldcmarkup_warned: + env.warn(env.docname, WARNING_MSG, self.lineno) + env.app._oldcmarkup_warned = True newname = 'c:' + self.name[1:] newdir = env.lookup_domain_element('directive', newname)[0] return newdir(newname, self.arguments, self.options, @@ -35,12 +42,16 @@ class OldCDirective(Directive): def old_crole(typ, rawtext, text, lineno, inliner, options={}, content=[]): env = inliner.document.settings.env + if not env.app._oldcmarkup_warned: + env.warn(env.docname, WARNING_MSG) + env.app._oldcmarkup_warned = True 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._oldcmarkup_warned = False app.add_directive('cfunction', OldCDirective) app.add_directive('cmember', OldCDirective) app.add_directive('cmacro', OldCDirective)