commit a22ebbda06cc38b4d0eeb358f9bb6f4a930086de Author: Damian Johnson atagar@torproject.org Date: Thu May 14 16:14:11 2020 -0700
Disable buggy cross referencing
Sphinx attempts to create cross-references for attribute and variable names...
https://github.com/sphinx-doc/sphinx/issues/2549 https://github.com/sphinx-doc/sphinx/issues/3866
This results in numerous warnings of the form...
WARNING: more than one target found for cross-reference 'digest'
Adapting a patch from the tickets above. Sphinx deprecated override_domain(), so using add_domain() instead...
https://www.sphinx-doc.org/en/2.0/extdev/appapi.html#sphinx.application.Sphi... --- docs/conf.py | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)
diff --git a/docs/conf.py b/docs/conf.py index aef0ff93..b880b114 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,6 +12,7 @@ # serve to show the default.
import sys, os +from sphinx.domains.python import PythonDomain
# If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -260,9 +261,35 @@ man_pages = [ trac_url = 'https://trac.torproject.org/%7Bslug%7D' spec_url = 'https://gitweb.torproject.org/torspec.git/commit/?id=%7Bslug%7D'
+ def skip_members(app, what, name, obj, skip, options): if name in ('ATTRIBUTES', 'PARSER_FOR_LINE'): return True # skip the descriptor's parser constants
+ +class PythonDomainNoXref(PythonDomain): + """ + Sphinx attempts to create cross-reference links for variable names... + + https://github.com/sphinx-doc/sphinx/issues/2549 + https://github.com/sphinx-doc/sphinx/issues/3866 + + This causes alot of warnings such as... + + stem/descriptor/networkstatus.py:docstring of + stem.descriptor.networkstatus.DocumentDigest:: WARNING: more than one + target found for cross-reference 'digest': + stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor.digest, ... + """ + + def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + if 'refspecific' in node: + del node['refspecific'] + + return super(PythonDomainNoXref, self).resolve_xref( + env, fromdocname, builder, typ, target, node, contnode) + + def setup(app): app.connect('autodoc-skip-member', skip_members) + app.add_domain(PythonDomainNoXref, override = True)