diff options
Diffstat (limited to 'sphinx/domains/python.py')
| -rw-r--r-- | sphinx/domains/python.py | 83 |
1 files changed, 51 insertions, 32 deletions
diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py index 2b46596af..0fe4b5eb4 100644 --- a/sphinx/domains/python.py +++ b/sphinx/domains/python.py @@ -12,16 +12,18 @@ import re from docutils import nodes -from docutils.parsers.rst import Directive, directives +from docutils.parsers.rst import directives from six import iteritems -from sphinx import addnodes +from sphinx import addnodes, locale +from sphinx.deprecation import DeprecatedDict, RemovedInSphinx30Warning from sphinx.directives import ObjectDescription from sphinx.domains import Domain, ObjType, Index -from sphinx.locale import l_, _ +from sphinx.locale import _, __ from sphinx.roles import XRefRole from sphinx.util import logging from sphinx.util.docfields import Field, GroupedField, TypedField +from sphinx.util.docutils import SphinxDirective from sphinx.util.nodes import make_refnode if False: @@ -44,6 +46,24 @@ py_sig_re = re.compile( ''', re.VERBOSE) +pairindextypes = { + 'module': _('module'), + 'keyword': _('keyword'), + 'operator': _('operator'), + 'object': _('object'), + 'exception': _('exception'), + 'statement': _('statement'), + 'builtin': _('built-in function'), +} # Dict[unicode, unicode] + +locale.pairindextypes = DeprecatedDict( + pairindextypes, + 'sphinx.locale.pairindextypes is deprecated. ' + 'Please use sphinx.domains.python.pairindextypes instead.', + RemovedInSphinx30Warning +) + + def _pseudo_parse_arglist(signode, arglist): # type: (addnodes.desc_signature, unicode) -> None """"Parse" a list of arguments separated by commas. @@ -173,21 +193,21 @@ class PyObject(ObjectDescription): } doc_field_types = [ - PyTypedField('parameter', label=l_('Parameters'), + PyTypedField('parameter', label=_('Parameters'), names=('param', 'parameter', 'arg', 'argument', 'keyword', 'kwarg', 'kwparam'), typerolename='class', typenames=('paramtype', 'type'), can_collapse=True), - PyTypedField('variable', label=l_('Variables'), rolename='obj', + PyTypedField('variable', label=_('Variables'), rolename='obj', names=('var', 'ivar', 'cvar'), typerolename='class', typenames=('vartype',), can_collapse=True), - PyGroupedField('exceptions', label=l_('Raises'), rolename='exc', + PyGroupedField('exceptions', label=_('Raises'), rolename='exc', names=('raises', 'raise', 'exception', 'except'), can_collapse=True), - Field('returnvalue', label=l_('Returns'), has_arg=False, + Field('returnvalue', label=_('Returns'), has_arg=False, names=('returns', 'return')), - PyField('returntype', label=l_('Return type'), has_arg=False, + PyField('returntype', label=_('Return type'), has_arg=False, names=('rtype',), bodyrolename='class'), ] @@ -536,7 +556,7 @@ class PyDecoratorMethod(PyDecoratorMixin, PyClassmember): return PyClassmember.run(self) -class PyModule(Directive): +class PyModule(SphinxDirective): """ Directive to mark description of a new module. """ @@ -554,19 +574,18 @@ class PyModule(Directive): def run(self): # type: () -> List[nodes.Node] - env = self.state.document.settings.env modname = self.arguments[0].strip() noindex = 'noindex' in self.options - env.ref_context['py:module'] = modname + self.env.ref_context['py:module'] = modname ret = [] if not noindex: - env.domaindata['py']['modules'][modname] = (env.docname, - self.options.get('synopsis', ''), - self.options.get('platform', ''), - 'deprecated' in self.options) + self.env.domaindata['py']['modules'][modname] = (self.env.docname, + self.options.get('synopsis', ''), + self.options.get('platform', ''), + 'deprecated' in self.options) # make a duplicate entry in 'objects' to facilitate searching for # the module in PythonDomain.find_obj() - env.domaindata['py']['objects'][modname] = (env.docname, 'module') + self.env.domaindata['py']['objects'][modname] = (self.env.docname, 'module') targetnode = nodes.target('', '', ids=['module-' + modname], ismod=True) self.state.document.note_explicit_target(targetnode) @@ -580,7 +599,7 @@ class PyModule(Directive): return ret -class PyCurrentModule(Directive): +class PyCurrentModule(SphinxDirective): """ This directive is just to tell Sphinx that we're documenting stuff in module foo, but links to module foo won't lead here. @@ -594,12 +613,11 @@ class PyCurrentModule(Directive): def run(self): # type: () -> List[nodes.Node] - env = self.state.document.settings.env modname = self.arguments[0].strip() if modname == 'None': - env.ref_context.pop('py:module', None) + self.env.ref_context.pop('py:module', None) else: - env.ref_context['py:module'] = modname + self.env.ref_context['py:module'] = modname return [] @@ -632,8 +650,8 @@ class PythonModuleIndex(Index): """ name = 'modindex' - localname = l_('Python Module Index') - shortname = l_('modules') + localname = _('Python Module Index') + shortname = _('modules') def generate(self, docnames=None): # type: (Iterable[unicode]) -> Tuple[List[Tuple[unicode, List[List[Union[unicode, int]]]]], bool] # NOQA @@ -703,15 +721,15 @@ class PythonDomain(Domain): name = 'py' label = 'Python' object_types = { - 'function': ObjType(l_('function'), 'func', 'obj'), - 'data': ObjType(l_('data'), 'data', 'obj'), - 'class': ObjType(l_('class'), 'class', 'exc', 'obj'), - 'exception': ObjType(l_('exception'), 'exc', 'class', 'obj'), - 'method': ObjType(l_('method'), 'meth', 'obj'), - 'classmethod': ObjType(l_('class method'), 'meth', 'obj'), - 'staticmethod': ObjType(l_('static method'), 'meth', 'obj'), - 'attribute': ObjType(l_('attribute'), 'attr', 'obj'), - 'module': ObjType(l_('module'), 'mod', 'obj'), + 'function': ObjType(_('function'), 'func', 'obj'), + 'data': ObjType(_('data'), 'data', 'obj'), + 'class': ObjType(_('class'), 'class', 'exc', 'obj'), + 'exception': ObjType(_('exception'), 'exc', 'class', 'obj'), + 'method': ObjType(_('method'), 'meth', 'obj'), + 'classmethod': ObjType(_('class method'), 'meth', 'obj'), + 'staticmethod': ObjType(_('static method'), 'meth', 'obj'), + 'attribute': ObjType(_('attribute'), 'attr', 'obj'), + 'module': ObjType(_('module'), 'mod', 'obj'), } # type: Dict[unicode, ObjType] directives = { @@ -841,7 +859,7 @@ class PythonDomain(Domain): if not matches: return None elif len(matches) > 1: - logger.warning('more than one target found for cross-reference %r: %s', + logger.warning(__('more than one target found for cross-reference %r: %s'), target, ', '.join(match[0] for match in matches), type='ref', subtype='python', location=node) name, obj = matches[0] @@ -912,6 +930,7 @@ def setup(app): return { 'version': 'builtin', + 'env_version': 1, 'parallel_read_safe': True, 'parallel_write_safe': True, } |