IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7236 from tk0miya/refactor_py_domain2

Browse Source 
py domain: Generate node_id for objects and modules in the right way
This commit is contained in:
Takeshi KOMIYA
2020-03-07 02:08:54 +09:00
committed by GitHub
parent d0cbeb28dc f13c546862
commit f329553a63
9 changed files with 147 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
CHANGES
View File

@@ -31,6 +31,10 @@ Incompatible changes
node_id for cross reference node_id for cross reference
* #7229: rst domain: Non intended behavior is removed such as ``numref_`` links * #7229: rst domain: Non intended behavior is removed such as ``numref_`` links
to ``.. rst:role:: numref`` to ``.. rst:role:: numref``
* #6903: py domain: Internal data structure has changed. Both objects and
modules have node_id for cross reference
* #6903: py domain: Non intended behavior is removed such as ``say_hello_``
links to ``.. py:function:: say_hello()``
Deprecated Deprecated
---------- ----------

3
doc/extdev/appapi.rst
View File

@@ -45,7 +45,6 @@ package.
.. automethod:: Sphinx.add_enumerable_node(node, figtype, title_getter=None, \*\*kwds) .. automethod:: Sphinx.add_enumerable_node(node, figtype, title_getter=None, \*\*kwds)
.. method:: Sphinx.add_directive(name, func, content, arguments, \*\*options)
.. automethod:: Sphinx.add_directive(name, directiveclass) .. automethod:: Sphinx.add_directive(name, directiveclass)
.. automethod:: Sphinx.add_role(name, role) .. automethod:: Sphinx.add_role(name, role)
@@ -54,7 +53,6 @@ package.
.. automethod:: Sphinx.add_domain(domain) .. automethod:: Sphinx.add_domain(domain)
.. method:: Sphinx.add_directive_to_domain(domain, name, func, content, arguments, \*\*options)
.. automethod:: Sphinx.add_directive_to_domain(domain, name, directiveclass) .. automethod:: Sphinx.add_directive_to_domain(domain, name, directiveclass)
.. automethod:: Sphinx.add_role_to_domain(domain, name, role) .. automethod:: Sphinx.add_role_to_domain(domain, name, role)
@@ -107,6 +105,7 @@ Emitting events
--------------- ---------------
.. class:: Sphinx .. class:: Sphinx
:noindex:
.. automethod:: emit(event, \*arguments) .. automethod:: emit(event, \*arguments)

5
doc/templating.rst
View File

@@ -227,6 +227,7 @@ them to generate links or output multiply used elements.
documents. documents.
.. function:: pathto(file, 1) .. function:: pathto(file, 1)
:noindex:
Return the path to a *file* which is a filename relative to the root of the Return the path to a *file* which is a filename relative to the root of the
generated output. Use this to refer to static files. generated output. Use this to refer to static files.
@@ -413,10 +414,6 @@ are in HTML form), these variables are also available:
nonempty if the :confval:`html_copy_source` value is ``True``. nonempty if the :confval:`html_copy_source` value is ``True``.
This has empty value on creating automatically-generated files. This has empty value on creating automatically-generated files.
.. data:: title
The page title.
.. data:: toc .. data:: toc
The local table of contents for the current page, rendered as HTML bullet The local table of contents for the current page, rendered as HTML bullet

1
doc/usage/extensions/autosummary.rst
View File

@@ -273,6 +273,7 @@ Additionally, the following filters are available
replaces the builtin Jinja `escape filter`_ that does html-escaping. replaces the builtin Jinja `escape filter`_ that does html-escaping.
.. function:: underline(s, line='=') .. function:: underline(s, line='=')
:noindex:
Add a title underline to a piece of text. Add a title underline to a piece of text.

121
sphinx/domains/python.py
View File

@@ -32,7 +32,7 @@ from sphinx.util import logging
from sphinx.util.docfields import Field, GroupedField, TypedField from sphinx.util.docfields import Field, GroupedField, TypedField
from sphinx.util.docutils import SphinxDirective from sphinx.util.docutils import SphinxDirective
from sphinx.util.inspect import signature_from_str from sphinx.util.inspect import signature_from_str
from sphinx.util.nodes import make_refnode from sphinx.util.nodes import make_id, make_refnode
from sphinx.util.typing import TextlikeNode from sphinx.util.typing import TextlikeNode
if False: if False:
@@ -358,19 +358,22 @@ class PyObject(ObjectDescription):
signode: desc_signature) -> None: signode: desc_signature) -> None:
modname = self.options.get('module', self.env.ref_context.get('py:module')) modname = self.options.get('module', self.env.ref_context.get('py:module'))
fullname = (modname + '.' if modname else '') + name_cls[0] fullname = (modname + '.' if modname else '') + name_cls[0]
# note target node_id = make_id(self.env, self.state.document, modname or '', name_cls[0])
if fullname not in self.state.document.ids: signode['ids'].append(node_id)
signode['names'].append(fullname)
signode['ids'].append(fullname)
self.state.document.note_explicit_target(signode)
domain = cast(PythonDomain, self.env.get_domain('py')) # Assign old styled node_id(fullname) not to break old hyperlinks (if possible)
domain.note_object(fullname, self.objtype, location=signode) # Note: Will removed in Sphinx-5.0 (RemovedInSphinx50Warning)
if node_id != fullname and fullname not in self.state.document.ids:
signode['ids'].append(fullname)
self.state.document.note_explicit_target(signode)
domain = cast(PythonDomain, self.env.get_domain('py'))
domain.note_object(fullname, self.objtype, node_id, location=signode)
indextext = self.get_index_text(modname, name_cls) indextext = self.get_index_text(modname, name_cls)
if indextext: if indextext:
self.indexnode['entries'].append(('single', indextext, self.indexnode['entries'].append(('single', indextext, node_id, '', None))
fullname, '', None))
def before_content(self) -> None: def before_content(self) -> None:
"""Handle object nesting before content """Handle object nesting before content
@@ -788,24 +791,43 @@ class PyModule(SphinxDirective):
ret = [] # type: List[Node] ret = [] # type: List[Node]
if not noindex: if not noindex:
# note module to the domain # note module to the domain
node_id = make_id(self.env, self.state.document, 'module', modname)
target = nodes.target('', '', ids=[node_id], ismod=True)
self.set_source_info(target)
# Assign old styled node_id not to break old hyperlinks (if possible)
# Note: Will removed in Sphinx-5.0 (RemovedInSphinx50Warning)
old_node_id = self.make_old_id(modname)
if node_id != old_node_id and old_node_id not in self.state.document.ids:
target['ids'].append(old_node_id)
self.state.document.note_explicit_target(target)
domain.note_module(modname, domain.note_module(modname,
node_id,
self.options.get('synopsis', ''), self.options.get('synopsis', ''),
self.options.get('platform', ''), self.options.get('platform', ''),
'deprecated' in self.options) 'deprecated' in self.options)
domain.note_object(modname, 'module', location=(self.env.docname, self.lineno)) domain.note_object(modname, 'module', node_id, location=target)
targetnode = nodes.target('', '', ids=['module-' + modname],
ismod=True)
self.state.document.note_explicit_target(targetnode)
# the platform and synopsis aren't printed; in fact, they are only # the platform and synopsis aren't printed; in fact, they are only
# used in the modindex currently # used in the modindex currently
ret.append(targetnode) ret.append(target)
indextext = _('%s (module)') % modname indextext = _('%s (module)') % modname
inode = addnodes.index(entries=[('single', indextext, inode = addnodes.index(entries=[('single', indextext, node_id, '', None)])
'module-' + modname, '', None)])
ret.append(inode) ret.append(inode)
return ret return ret
def make_old_id(self, name: str) -> str:
"""Generate old styled node_id.
Old styled node_id is incompatible with docutils' node_id.
It can contain dots and hyphens.
.. note:: Old styled node_id was mainly used until Sphinx-3.0.
"""
return 'module-%s' % name
class PyCurrentModule(SphinxDirective): class PyCurrentModule(SphinxDirective):
""" """
@@ -888,7 +910,7 @@ class PythonModuleIndex(Index):
# sort out collapsable modules # sort out collapsable modules
prev_modname = '' prev_modname = ''
num_toplevels = 0 num_toplevels = 0
for modname, (docname, synopsis, platforms, deprecated) in modules: for modname, (docname, node_id, synopsis, platforms, deprecated) in modules:
if docnames and docname not in docnames: if docnames and docname not in docnames:
continue continue
@@ -925,8 +947,7 @@ class PythonModuleIndex(Index):
qualifier = _('Deprecated') if deprecated else '' qualifier = _('Deprecated') if deprecated else ''
entries.append(IndexEntry(stripped + modname, subtype, docname, entries.append(IndexEntry(stripped + modname, subtype, docname,
'module-' + stripped + modname, platforms, node_id, platforms, qualifier, synopsis))
qualifier, synopsis))
prev_modname = modname prev_modname = modname
# apply heuristics when to collapse modindex at page load: # apply heuristics when to collapse modindex at page load:
@@ -990,10 +1011,10 @@ class PythonDomain(Domain):
] ]
@property @property
def objects(self) -> Dict[str, Tuple[str, str]]: def objects(self) -> Dict[str, Tuple[str, str, str]]:
return self.data.setdefault('objects', {}) # fullname -> docname, objtype return self.data.setdefault('objects', {}) # fullname -> docname, node_id, objtype
def note_object(self, name: str, objtype: str, location: Any = None) -> None: def note_object(self, name: str, objtype: str, node_id: str, location: Any = None) -> None:
"""Note a python object for cross reference. """Note a python object for cross reference.
.. versionadded:: 2.1 .. versionadded:: 2.1
@@ -1003,39 +1024,40 @@ class PythonDomain(Domain):
logger.warning(__('duplicate object description of %s, ' logger.warning(__('duplicate object description of %s, '
'other instance in %s, use :noindex: for one of them'), 'other instance in %s, use :noindex: for one of them'),
name, docname, location=location) name, docname, location=location)
self.objects[name] = (self.env.docname, objtype) self.objects[name] = (self.env.docname, node_id, objtype)
@property @property
def modules(self) -> Dict[str, Tuple[str, str, str, bool]]: def modules(self) -> Dict[str, Tuple[str, str, str, str, bool]]:
return self.data.setdefault('modules', {}) # modname -> docname, synopsis, platform, deprecated # NOQA return self.data.setdefault('modules', {}) # modname -> docname, node_id, synopsis, platform, deprecated # NOQA
def note_module(self, name: str, synopsis: str, platform: str, deprecated: bool) -> None: def note_module(self, name: str, node_id: str, synopsis: str,
platform: str, deprecated: bool) -> None:
"""Note a python module for cross reference. """Note a python module for cross reference.
.. versionadded:: 2.1 .. versionadded:: 2.1
""" """
self.modules[name] = (self.env.docname, synopsis, platform, deprecated) self.modules[name] = (self.env.docname, node_id, synopsis, platform, deprecated)
def clear_doc(self, docname: str) -> None: def clear_doc(self, docname: str) -> None:
for fullname, (fn, _l) in list(self.objects.items()): for fullname, (fn, _x, _x) in list(self.objects.items()):
if fn == docname: if fn == docname:
del self.objects[fullname] del self.objects[fullname]
for modname, (fn, _x, _x, _y) in list(self.modules.items()): for modname, (fn, _x, _x, _x, _y) in list(self.modules.items()):
if fn == docname: if fn == docname:
del self.modules[modname] del self.modules[modname]
def merge_domaindata(self, docnames: List[str], otherdata: Dict) -> None: def merge_domaindata(self, docnames: List[str], otherdata: Dict) -> None:
# XXX check duplicates? # XXX check duplicates?
for fullname, (fn, objtype) in otherdata['objects'].items(): for fullname, (fn, node_id, objtype) in otherdata['objects'].items():
if fn in docnames: if fn in docnames:
self.objects[fullname] = (fn, objtype) self.objects[fullname] = (fn, node_id, objtype)
for modname, data in otherdata['modules'].items(): for modname, data in otherdata['modules'].items():
if data[0] in docnames: if data[0] in docnames:
self.modules[modname] = data self.modules[modname] = data
def find_obj(self, env: BuildEnvironment, modname: str, classname: str, def find_obj(self, env: BuildEnvironment, modname: str, classname: str,
name: str, type: str, searchmode: int = 0 name: str, type: str, searchmode: int = 0
) -> List[Tuple[str, Tuple[str, str]]]: ) -> List[Tuple[str, Tuple[str, str, str]]]:
"""Find a Python object for "name", perhaps using the given module """Find a Python object for "name", perhaps using the given module
and/or classname. Returns a list of (name, object entry) tuples. and/or classname. Returns a list of (name, object entry) tuples.
""" """
@@ -1046,7 +1068,7 @@ class PythonDomain(Domain):
if not name: if not name:
return [] return []
matches = [] # type: List[Tuple[str, Tuple[str, str]]] matches = [] # type: List[Tuple[str, Tuple[str, str, str]]]
newname = None newname = None
if searchmode == 1: if searchmode == 1:
@@ -1057,20 +1079,20 @@ class PythonDomain(Domain):
if objtypes is not None: if objtypes is not None:
if modname and classname: if modname and classname:
fullname = modname + '.' + classname + '.' + name fullname = modname + '.' + classname + '.' + name
if fullname in self.objects and self.objects[fullname][1] in objtypes: if fullname in self.objects and self.objects[fullname][2] in objtypes:
newname = fullname newname = fullname
if not newname: if not newname:
if modname and modname + '.' + name in self.objects and \ if modname and modname + '.' + name in self.objects and \
self.objects[modname + '.' + name][1] in objtypes: self.objects[modname + '.' + name][2] in objtypes:
newname = modname + '.' + name newname = modname + '.' + name
elif name in self.objects and self.objects[name][1] in objtypes: elif name in self.objects and self.objects[name][2] in objtypes:
newname = name newname = name
else: else:
# "fuzzy" searching mode # "fuzzy" searching mode
searchname = '.' + name searchname = '.' + name
matches = [(oname, self.objects[oname]) for oname in self.objects matches = [(oname, self.objects[oname]) for oname in self.objects
if oname.endswith(searchname) and if oname.endswith(searchname) and
self.objects[oname][1] in objtypes] self.objects[oname][2] in objtypes]
else: else:
# NOTE: searching for exact match, object type is not considered # NOTE: searching for exact match, object type is not considered
if name in self.objects: if name in self.objects:
@@ -1118,10 +1140,10 @@ class PythonDomain(Domain):
type='ref', subtype='python', location=node) type='ref', subtype='python', location=node)
name, obj = matches[0] name, obj = matches[0]
if obj[1] == 'module': if obj[2] == 'module':
return self._make_module_refnode(builder, fromdocname, name, contnode) return self._make_module_refnode(builder, fromdocname, name, contnode)
else: else:
return make_refnode(builder, fromdocname, obj[0], name, contnode, name) return make_refnode(builder, fromdocname, obj[0], obj[1], contnode, name)
def resolve_any_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder, def resolve_any_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
target: str, node: pending_xref, contnode: Element target: str, node: pending_xref, contnode: Element
@@ -1133,20 +1155,20 @@ class PythonDomain(Domain):
# always search in "refspecific" mode with the :any: role # always search in "refspecific" mode with the :any: role
matches = self.find_obj(env, modname, clsname, target, None, 1) matches = self.find_obj(env, modname, clsname, target, None, 1)
for name, obj in matches: for name, obj in matches:
if obj[1] == 'module': if obj[2] == 'module':
results.append(('py:mod', results.append(('py:mod',
self._make_module_refnode(builder, fromdocname, self._make_module_refnode(builder, fromdocname,
name, contnode))) name, contnode)))
else: else:
results.append(('py:' + self.role_for_objtype(obj[1]), results.append(('py:' + self.role_for_objtype(obj[2]),
make_refnode(builder, fromdocname, obj[0], name, make_refnode(builder, fromdocname, obj[0], obj[1],
contnode, name))) contnode, name)))
return results return results
def _make_module_refnode(self, builder: Builder, fromdocname: str, name: str, def _make_module_refnode(self, builder: Builder, fromdocname: str, name: str,
contnode: Node) -> Element: contnode: Node) -> Element:
# get additional info for modules # get additional info for modules
docname, synopsis, platform, deprecated = self.modules[name] docname, node_id, synopsis, platform, deprecated = self.modules[name]
title = name title = name
if synopsis: if synopsis:
title += ': ' + synopsis title += ': ' + synopsis
@@ -1154,15 +1176,14 @@ class PythonDomain(Domain):
title += _(' (deprecated)') title += _(' (deprecated)')
if platform: if platform:
title += ' (' + platform + ')' title += ' (' + platform + ')'
return make_refnode(builder, fromdocname, docname, return make_refnode(builder, fromdocname, docname, node_id, contnode, title)
'module-' + name, contnode, title)
def get_objects(self) -> Iterator[Tuple[str, str, str, str, str, int]]: def get_objects(self) -> Iterator[Tuple[str, str, str, str, str, int]]:
for modname, info in self.modules.items(): for modname, info in self.modules.items():
yield (modname, modname, 'module', info[0], 'module-' + modname, 0) yield (modname, modname, 'module', info[0], info[1], 0)
for refname, (docname, type) in self.objects.items(): for refname, (docname, node_id, type) in self.objects.items():
if type != 'module': # modules are already handled if type != 'module': # modules are already handled
yield (refname, refname, type, docname, refname, 1) yield (refname, refname, type, docname, node_id, 1)
def get_full_qualified_name(self, node: Element) -> str: def get_full_qualified_name(self, node: Element) -> str:
modname = node.get('py:module') modname = node.get('py:module')
@@ -1182,7 +1203,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
return { return {
'version': 'builtin', 'version': 'builtin',
'env_version': 1, 'env_version': 2,
'parallel_read_safe': True, 'parallel_read_safe': True,
'parallel_write_safe': True, 'parallel_write_safe': True,
} }

18
tests/test_build_html.py
View File

@@ -176,8 +176,8 @@ def test_html4_output(app, status, warning):
r'-| |-'), r'-| |-'),
], ],
'autodoc.html': [ 'autodoc.html': [
(".//dl[@class='py class']/dt[@id='autodoc_target.Class']", ''), (".//dl[@class='py class']/dt[@id='autodoc-target-class']", ''),
(".//dl[@class='py function']/dt[@id='autodoc_target.function']/em", r'\*\*kwds'), (".//dl[@class='py function']/dt[@id='autodoc-target-function']/em", r'\*\*kwds'),
(".//dd/p", r'Return spam\.'), (".//dd/p", r'Return spam\.'),
], ],
'extapi.html': [ 'extapi.html': [
@@ -262,7 +262,7 @@ def test_html4_output(app, status, warning):
(".//p", 'Always present'), (".//p", 'Always present'),
# tests for ``any`` role # tests for ``any`` role
(".//a[@href='#with']/span", 'headings'), (".//a[@href='#with']/span", 'headings'),
(".//a[@href='objects.html#func_without_body']/code/span", 'objects'), (".//a[@href='objects.html#func-without-body']/code/span", 'objects'),
# tests for numeric labels # tests for numeric labels
(".//a[@href='#id1'][@class='reference internal']/span", 'Testing various markup'), (".//a[@href='#id1'][@class='reference internal']/span", 'Testing various markup'),
# tests for smartypants # tests for smartypants
@@ -274,18 +274,18 @@ def test_html4_output(app, status, warning):
(".//p", 'Il dit : « C’est “super” ! »'), (".//p", 'Il dit : « C’est “super” ! »'),
], ],
'objects.html': [ 'objects.html': [
(".//dt[@id='mod.Cls.meth1']", ''), (".//dt[@id='mod-cls-meth1']", ''),
(".//dt[@id='errmod.Error']", ''), (".//dt[@id='errmod-error']", ''),
(".//dt/code", r'long\(parameter,\s* list\)'), (".//dt/code", r'long\(parameter,\s* list\)'),
(".//dt/code", 'another one'), (".//dt/code", 'another one'),
(".//a[@href='#mod.Cls'][@class='reference internal']", ''), (".//a[@href='#mod-cls'][@class='reference internal']", ''),
(".//dl[@class='std userdesc']", ''), (".//dl[@class='std userdesc']", ''),
(".//dt[@id='userdesc-myobj']", ''), (".//dt[@id='userdesc-myobj']", ''),
(".//a[@href='#userdesc-myobj'][@class='reference internal']", ''), (".//a[@href='#userdesc-myobj'][@class='reference internal']", ''),
# docfields # docfields
(".//a[@class='reference internal'][@href='#TimeInt']/em", 'TimeInt'), (".//a[@class='reference internal'][@href='#timeint']/em", 'TimeInt'),
(".//a[@class='reference internal'][@href='#Time']", 'Time'), (".//a[@class='reference internal'][@href='#time']", 'Time'),
(".//a[@class='reference internal'][@href='#errmod.Error']/strong", 'Error'), (".//a[@class='reference internal'][@href='#errmod-error']/strong", 'Error'),
# C references # C references
(".//span[@class='pre']", 'CFunction()'), (".//span[@class='pre']", 'CFunction()'),
(".//a[@href='#c.Sphinx_DoSomething']", ''), (".//a[@href='#c.Sphinx_DoSomething']", ''),

111
tests/test_domain_py.py
View File

@@ -145,24 +145,24 @@ def test_domain_py_objects(app, status, warning):
assert 'module_b.submodule' in modules assert 'module_b.submodule' in modules
assert 'module_b.submodule' in objects assert 'module_b.submodule' in objects
assert objects['module_a.submodule.ModTopLevel'] == ('module', 'class') assert objects['module_a.submodule.ModTopLevel'][2] == 'class'
assert objects['module_a.submodule.ModTopLevel.mod_child_1'] == ('module', 'method') assert objects['module_a.submodule.ModTopLevel.mod_child_1'][2] == 'method'
assert objects['module_a.submodule.ModTopLevel.mod_child_2'] == ('module', 'method') assert objects['module_a.submodule.ModTopLevel.mod_child_2'][2] == 'method'
assert 'ModTopLevel.ModNoModule' not in objects assert 'ModTopLevel.ModNoModule' not in objects
assert objects['ModNoModule'] == ('module', 'class') assert objects['ModNoModule'][2] == 'class'
assert objects['module_b.submodule.ModTopLevel'] == ('module', 'class') assert objects['module_b.submodule.ModTopLevel'][2] == 'class'
assert objects['TopLevel'] == ('roles', 'class') assert objects['TopLevel'][2] == 'class'
assert objects['top_level'] == ('roles', 'method') assert objects['top_level'][2] == 'method'
assert objects['NestedParentA'] == ('roles', 'class') assert objects['NestedParentA'][2] == 'class'
assert objects['NestedParentA.child_1'] == ('roles', 'method') assert objects['NestedParentA.child_1'][2] == 'method'
assert objects['NestedParentA.any_child'] == ('roles', 'method') assert objects['NestedParentA.any_child'][2] == 'method'
assert objects['NestedParentA.NestedChildA'] == ('roles', 'class') assert objects['NestedParentA.NestedChildA'][2] == 'class'
assert objects['NestedParentA.NestedChildA.subchild_1'] == ('roles', 'method') assert objects['NestedParentA.NestedChildA.subchild_1'][2] == 'method'
assert objects['NestedParentA.NestedChildA.subchild_2'] == ('roles', 'method') assert objects['NestedParentA.NestedChildA.subchild_2'][2] == 'method'
assert objects['NestedParentA.child_2'] == ('roles', 'method') assert objects['NestedParentA.child_2'][2] == 'method'
assert objects['NestedParentB'] == ('roles', 'class') assert objects['NestedParentB'][2] == 'class'
assert objects['NestedParentB.child_1'] == ('roles', 'method') assert objects['NestedParentB.child_1'][2] == 'method'
@pytest.mark.sphinx('html', testroot='domain-py') @pytest.mark.sphinx('html', testroot='domain-py')
@@ -170,11 +170,11 @@ def test_resolve_xref_for_properties(app, status, warning):
app.builder.build_all() app.builder.build_all()
content = (app.outdir / 'module.html').read_text() content = (app.outdir / 'module.html').read_text()
assert ('Link to <a class="reference internal" href="#module_a.submodule.ModTopLevel.prop"' assert ('Link to <a class="reference internal" href="#module-a-submodule-modtoplevel-prop"'
' title="module_a.submodule.ModTopLevel.prop">' ' title="module_a.submodule.ModTopLevel.prop">'
'<code class="xref py py-attr docutils literal notranslate"><span class="pre">' '<code class="xref py py-attr docutils literal notranslate"><span class="pre">'
'prop</span> <span class="pre">attribute</span></code></a>' in content) 'prop</span> <span class="pre">attribute</span></code></a>' in content)
assert ('Link to <a class="reference internal" href="#module_a.submodule.ModTopLevel.prop"' assert ('Link to <a class="reference internal" href="#module-a-submodule-modtoplevel-prop"'
' title="module_a.submodule.ModTopLevel.prop">' ' title="module_a.submodule.ModTopLevel.prop">'
'<code class="xref py py-meth docutils literal notranslate"><span class="pre">' '<code class="xref py py-meth docutils literal notranslate"><span class="pre">'
'prop</span> <span class="pre">method</span></code></a>' in content) 'prop</span> <span class="pre">method</span></code></a>' in content)
@@ -191,17 +191,20 @@ def test_domain_py_find_obj(app, status, warning):
assert (find_obj(None, None, 'NONEXISTANT', 'class') == []) assert (find_obj(None, None, 'NONEXISTANT', 'class') == [])
assert (find_obj(None, None, 'NestedParentA', 'class') == assert (find_obj(None, None, 'NestedParentA', 'class') ==
[('NestedParentA', ('roles', 'class'))]) [('NestedParentA', ('roles', 'nestedparenta', 'class'))])
assert (find_obj(None, None, 'NestedParentA.NestedChildA', 'class') == assert (find_obj(None, None, 'NestedParentA.NestedChildA', 'class') ==
[('NestedParentA.NestedChildA', ('roles', 'class'))]) [('NestedParentA.NestedChildA', ('roles', 'nestedparenta-nestedchilda', 'class'))])
assert (find_obj(None, 'NestedParentA', 'NestedChildA', 'class') == assert (find_obj(None, 'NestedParentA', 'NestedChildA', 'class') ==
[('NestedParentA.NestedChildA', ('roles', 'class'))]) [('NestedParentA.NestedChildA', ('roles', 'nestedparenta-nestedchilda', 'class'))])
assert (find_obj(None, None, 'NestedParentA.NestedChildA.subchild_1', 'meth') == assert (find_obj(None, None, 'NestedParentA.NestedChildA.subchild_1', 'meth') ==
[('NestedParentA.NestedChildA.subchild_1', ('roles', 'method'))]) [('NestedParentA.NestedChildA.subchild_1',
('roles', 'nestedparenta-nestedchilda-subchild-1', 'method'))])
assert (find_obj(None, 'NestedParentA', 'NestedChildA.subchild_1', 'meth') == assert (find_obj(None, 'NestedParentA', 'NestedChildA.subchild_1', 'meth') ==
[('NestedParentA.NestedChildA.subchild_1', ('roles', 'method'))]) [('NestedParentA.NestedChildA.subchild_1',
('roles', 'nestedparenta-nestedchilda-subchild-1', 'method'))])
assert (find_obj(None, 'NestedParentA.NestedChildA', 'subchild_1', 'meth') == assert (find_obj(None, 'NestedParentA.NestedChildA', 'subchild_1', 'meth') ==
[('NestedParentA.NestedChildA.subchild_1', ('roles', 'method'))]) [('NestedParentA.NestedChildA.subchild_1',
('roles', 'nestedparenta-nestedchilda-subchild-1', 'method'))])
def test_get_full_qualified_name(): def test_get_full_qualified_name():
@@ -402,7 +405,7 @@ def test_pydata(app):
[desc, ([desc_signature, desc_name, "var"], [desc, ([desc_signature, desc_name, "var"],
[desc_content, ()])])) [desc_content, ()])]))
assert 'var' in domain.objects assert 'var' in domain.objects
assert domain.objects['var'] == ('index', 'data') assert domain.objects['var'] == ('index', 'var', 'data')
def test_pyfunction(app): def test_pyfunction(app):
@@ -421,9 +424,9 @@ def test_pyfunction(app):
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])])) [desc_content, ()])]))
assert 'func1' in domain.objects assert 'func1' in domain.objects
assert domain.objects['func1'] == ('index', 'function') assert domain.objects['func1'] == ('index', 'func1', 'function')
assert 'func2' in domain.objects assert 'func2' in domain.objects
assert domain.objects['func2'] == ('index', 'function') assert domain.objects['func2'] == ('index', 'func2', 'function')
def test_pymethod_options(app): def test_pymethod_options(app):
@@ -460,61 +463,61 @@ def test_pymethod_options(app):
# method # method
assert_node(doctree[1][1][0], addnodes.index, assert_node(doctree[1][1][0], addnodes.index,
entries=[('single', 'meth1() (Class method)', 'Class.meth1', '', None)]) entries=[('single', 'meth1() (Class method)', 'class-meth1', '', None)])
assert_node(doctree[1][1][1], ([desc_signature, ([desc_name, "meth1"], assert_node(doctree[1][1][1], ([desc_signature, ([desc_name, "meth1"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
assert 'Class.meth1' in domain.objects assert 'Class.meth1' in domain.objects
assert domain.objects['Class.meth1'] == ('index', 'method') assert domain.objects['Class.meth1'] == ('index', 'class-meth1', 'method')
# :classmethod: # :classmethod:
assert_node(doctree[1][1][2], addnodes.index, assert_node(doctree[1][1][2], addnodes.index,
entries=[('single', 'meth2() (Class class method)', 'Class.meth2', '', None)]) entries=[('single', 'meth2() (Class class method)', 'class-meth2', '', None)])
assert_node(doctree[1][1][3], ([desc_signature, ([desc_annotation, "classmethod "], assert_node(doctree[1][1][3], ([desc_signature, ([desc_annotation, "classmethod "],
[desc_name, "meth2"], [desc_name, "meth2"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
assert 'Class.meth2' in domain.objects assert 'Class.meth2' in domain.objects
assert domain.objects['Class.meth2'] == ('index', 'method') assert domain.objects['Class.meth2'] == ('index', 'class-meth2', 'method')
# :staticmethod: # :staticmethod:
assert_node(doctree[1][1][4], addnodes.index, assert_node(doctree[1][1][4], addnodes.index,
entries=[('single', 'meth3() (Class static method)', 'Class.meth3', '', None)]) entries=[('single', 'meth3() (Class static method)', 'class-meth3', '', None)])
assert_node(doctree[1][1][5], ([desc_signature, ([desc_annotation, "static "], assert_node(doctree[1][1][5], ([desc_signature, ([desc_annotation, "static "],
[desc_name, "meth3"], [desc_name, "meth3"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
assert 'Class.meth3' in domain.objects assert 'Class.meth3' in domain.objects
assert domain.objects['Class.meth3'] == ('index', 'method') assert domain.objects['Class.meth3'] == ('index', 'class-meth3', 'method')
# :async: # :async:
assert_node(doctree[1][1][6], addnodes.index, assert_node(doctree[1][1][6], addnodes.index,
entries=[('single', 'meth4() (Class method)', 'Class.meth4', '', None)]) entries=[('single', 'meth4() (Class method)', 'class-meth4', '', None)])
assert_node(doctree[1][1][7], ([desc_signature, ([desc_annotation, "async "], assert_node(doctree[1][1][7], ([desc_signature, ([desc_annotation, "async "],
[desc_name, "meth4"], [desc_name, "meth4"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
assert 'Class.meth4' in domain.objects assert 'Class.meth4' in domain.objects
assert domain.objects['Class.meth4'] == ('index', 'method') assert domain.objects['Class.meth4'] == ('index', 'class-meth4', 'method')
# :property: # :property:
assert_node(doctree[1][1][8], addnodes.index, assert_node(doctree[1][1][8], addnodes.index,
entries=[('single', 'meth5() (Class property)', 'Class.meth5', '', None)]) entries=[('single', 'meth5() (Class property)', 'class-meth5', '', None)])
assert_node(doctree[1][1][9], ([desc_signature, ([desc_annotation, "property "], assert_node(doctree[1][1][9], ([desc_signature, ([desc_annotation, "property "],
[desc_name, "meth5"])], [desc_name, "meth5"])],
[desc_content, ()])) [desc_content, ()]))
assert 'Class.meth5' in domain.objects assert 'Class.meth5' in domain.objects
assert domain.objects['Class.meth5'] == ('index', 'method') assert domain.objects['Class.meth5'] == ('index', 'class-meth5', 'method')
# :abstractmethod: # :abstractmethod:
assert_node(doctree[1][1][10], addnodes.index, assert_node(doctree[1][1][10], addnodes.index,
entries=[('single', 'meth6() (Class method)', 'Class.meth6', '', None)]) entries=[('single', 'meth6() (Class method)', 'class-meth6', '', None)])
assert_node(doctree[1][1][11], ([desc_signature, ([desc_annotation, "abstract "], assert_node(doctree[1][1][11], ([desc_signature, ([desc_annotation, "abstract "],
[desc_name, "meth6"], [desc_name, "meth6"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
assert 'Class.meth6' in domain.objects assert 'Class.meth6' in domain.objects
assert domain.objects['Class.meth6'] == ('index', 'method') assert domain.objects['Class.meth6'] == ('index', 'class-meth6', 'method')
def test_pyclassmethod(app): def test_pyclassmethod(app):
@@ -529,13 +532,13 @@ def test_pyclassmethod(app):
[desc_content, (addnodes.index, [desc_content, (addnodes.index,
desc)])])) desc)])]))
assert_node(doctree[1][1][0], addnodes.index, assert_node(doctree[1][1][0], addnodes.index,
entries=[('single', 'meth() (Class class method)', 'Class.meth', '', None)]) entries=[('single', 'meth() (Class class method)', 'class-meth', '', None)])
assert_node(doctree[1][1][1], ([desc_signature, ([desc_annotation, "classmethod "], assert_node(doctree[1][1][1], ([desc_signature, ([desc_annotation, "classmethod "],
[desc_name, "meth"], [desc_name, "meth"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
assert 'Class.meth' in domain.objects assert 'Class.meth' in domain.objects
assert domain.objects['Class.meth'] == ('index', 'method') assert domain.objects['Class.meth'] == ('index', 'class-meth', 'method')
def test_pystaticmethod(app): def test_pystaticmethod(app):
@@ -550,13 +553,13 @@ def test_pystaticmethod(app):
[desc_content, (addnodes.index, [desc_content, (addnodes.index,
desc)])])) desc)])]))
assert_node(doctree[1][1][0], addnodes.index, assert_node(doctree[1][1][0], addnodes.index,
entries=[('single', 'meth() (Class static method)', 'Class.meth', '', None)]) entries=[('single', 'meth() (Class static method)', 'class-meth', '', None)])
assert_node(doctree[1][1][1], ([desc_signature, ([desc_annotation, "static "], assert_node(doctree[1][1][1], ([desc_signature, ([desc_annotation, "static "],
[desc_name, "meth"], [desc_name, "meth"],
[desc_parameterlist, ()])], [desc_parameterlist, ()])],
[desc_content, ()])) [desc_content, ()]))
assert 'Class.meth' in domain.objects assert 'Class.meth' in domain.objects
assert domain.objects['Class.meth'] == ('index', 'method') assert domain.objects['Class.meth'] == ('index', 'class-meth', 'method')
def test_pyattribute(app): def test_pyattribute(app):
@@ -573,13 +576,13 @@ def test_pyattribute(app):
[desc_content, (addnodes.index, [desc_content, (addnodes.index,
desc)])])) desc)])]))
assert_node(doctree[1][1][0], addnodes.index, assert_node(doctree[1][1][0], addnodes.index,
entries=[('single', 'attr (Class attribute)', 'Class.attr', '', None)]) entries=[('single', 'attr (Class attribute)', 'class-attr', '', None)])
assert_node(doctree[1][1][1], ([desc_signature, ([desc_name, "attr"], assert_node(doctree[1][1][1], ([desc_signature, ([desc_name, "attr"],
[desc_annotation, ": str"], [desc_annotation, ": str"],
[desc_annotation, " = ''"])], [desc_annotation, " = ''"])],
[desc_content, ()])) [desc_content, ()]))
assert 'Class.attr' in domain.objects assert 'Class.attr' in domain.objects
assert domain.objects['Class.attr'] == ('index', 'attribute') assert domain.objects['Class.attr'] == ('index', 'class-attr', 'attribute')
@pytest.mark.sphinx(freshenv=True) @pytest.mark.sphinx(freshenv=True)
@@ -595,10 +598,10 @@ def test_module_index(app):
assert index.generate() == ( assert index.generate() == (
[('d', [IndexEntry('docutils', 0, 'index', 'module-docutils', '', '', '')]), [('d', [IndexEntry('docutils', 0, 'index', 'module-docutils', '', '', '')]),
('s', [IndexEntry('sphinx', 1, 'index', 'module-sphinx', '', '', ''), ('s', [IndexEntry('sphinx', 1, 'index', 'module-sphinx', '', '', ''),
IndexEntry('sphinx.builders', 2, 'index', 'module-sphinx.builders', '', '', ''), # NOQA IndexEntry('sphinx.builders', 2, 'index', 'module-sphinx-builders', '', '', ''), # NOQA
IndexEntry('sphinx.builders.html', 2, 'index', 'module-sphinx.builders.html', '', '', ''), # NOQA IndexEntry('sphinx.builders.html', 2, 'index', 'module-sphinx-builders-html', '', '', ''), # NOQA
IndexEntry('sphinx.config', 2, 'index', 'module-sphinx.config', '', '', ''), IndexEntry('sphinx.config', 2, 'index', 'module-sphinx-config', '', '', ''),
IndexEntry('sphinx_intl', 0, 'index', 'module-sphinx_intl', '', '', '')])], IndexEntry('sphinx_intl', 0, 'index', 'module-sphinx-intl', '', '', '')])],
False False
) )
@@ -610,7 +613,7 @@ def test_module_index_submodule(app):
index = PythonModuleIndex(app.env.get_domain('py')) index = PythonModuleIndex(app.env.get_domain('py'))
assert index.generate() == ( assert index.generate() == (
[('s', [IndexEntry('sphinx', 1, '', '', '', '', ''), [('s', [IndexEntry('sphinx', 1, '', '', '', '', ''),
IndexEntry('sphinx.config', 2, 'index', 'module-sphinx.config', '', '', '')])], IndexEntry('sphinx.config', 2, 'index', 'module-sphinx-config', '', '', '')])],
False False
) )
@@ -639,12 +642,12 @@ def test_modindex_common_prefix(app):
restructuredtext.parse(app, text) restructuredtext.parse(app, text)
index = PythonModuleIndex(app.env.get_domain('py')) index = PythonModuleIndex(app.env.get_domain('py'))
assert index.generate() == ( assert index.generate() == (
[('b', [IndexEntry('sphinx.builders', 1, 'index', 'module-sphinx.builders', '', '', ''), # NOQA [('b', [IndexEntry('sphinx.builders', 1, 'index', 'module-sphinx-builders', '', '', ''), # NOQA
IndexEntry('sphinx.builders.html', 2, 'index', 'module-sphinx.builders.html', '', '', '')]), # NOQA IndexEntry('sphinx.builders.html', 2, 'index', 'module-sphinx-builders-html', '', '', '')]), # NOQA
('c', [IndexEntry('sphinx.config', 0, 'index', 'module-sphinx.config', '', '', '')]), ('c', [IndexEntry('sphinx.config', 0, 'index', 'module-sphinx-config', '', '', '')]),
('d', [IndexEntry('docutils', 0, 'index', 'module-docutils', '', '', '')]), ('d', [IndexEntry('docutils', 0, 'index', 'module-docutils', '', '', '')]),
('s', [IndexEntry('sphinx', 0, 'index', 'module-sphinx', '', '', ''), ('s', [IndexEntry('sphinx', 0, 'index', 'module-sphinx', '', '', ''),
IndexEntry('sphinx_intl', 0, 'index', 'module-sphinx_intl', '', '', '')])], IndexEntry('sphinx_intl', 0, 'index', 'module-sphinx-intl', '', '', '')])],
True True
) )

4
tests/test_environment.py
View File

@@ -84,7 +84,7 @@ def test_object_inventory(app):
refs = app.env.domaindata['py']['objects'] refs = app.env.domaindata['py']['objects']
assert 'func_without_module' in refs assert 'func_without_module' in refs
assert refs['func_without_module'] == ('objects', 'function') assert refs['func_without_module'] == ('objects', 'func-without-module', 'function')
assert 'func_without_module2' in refs assert 'func_without_module2' in refs
assert 'mod.func_in_module' in refs assert 'mod.func_in_module' in refs
assert 'mod.Cls' in refs assert 'mod.Cls' in refs
@@ -99,7 +99,7 @@ def test_object_inventory(app):
assert 'func_noindex' not in refs assert 'func_noindex' not in refs
assert app.env.domaindata['py']['modules']['mod'] == \ assert app.env.domaindata['py']['modules']['mod'] == \
('objects', 'Module synopsis.', 'UNIX', False) ('objects', 'module-mod', 'Module synopsis.', 'UNIX', False)
assert app.env.domains['py'].data is app.env.domaindata['py'] assert app.env.domains['py'].data is app.env.domaindata['py']
assert app.env.domains['c'].data is app.env.domaindata['c'] assert app.env.domains['c'].data is app.env.domaindata['c']

2
tests/test_intl.py
View File

@@ -870,7 +870,7 @@ def test_xml_refs_in_python_domain(app):
assert_elem( assert_elem(
para0[0], para0[0],
['SEE THIS DECORATOR:', 'sensitive_variables()', '.'], ['SEE THIS DECORATOR:', 'sensitive_variables()', '.'],
['sensitive.sensitive_variables']) ['sensitive-sensitive-variables'])
@sphinx_intl @sphinx_intl