more than one target found for cross reference should prefer current file's method over other libraries methods #4961
Comments
|
Where can I see the content of
|
As you could find out in that link, the source code can be found for example here: https://phabricator.wikimedia.org/diffusion/PWBC/. Also you could look to https://pypi.org/project/pywikibot/. Sphinx config is in the docs/ folder. Dependencies for Sphinx are written in docs/conf.py and tox.ini's [testenv:doc] (or I could collect them into one list and send them to you, if there will be any problem). The Sphinx build live can be found here: https://doc.wikimedia.org/pywikibot/ The file in the description is stored in pywikibot/ folder. But if you search through build log, you could see there is also a bunch of other similar ones. Today, I wanted to clean "more than one target found for cross reference" warnings, but I found out many of them have this issue. If there will be any problem, I'll write more detailed step-by-step quide to build our docs. |
|
Confirmed with this Dockerfile: I understand the issue.
At present, there are no way to tell the objects in the file to Sphinx. The autodoc extension only generates reST file. And Sphinx-core only converts it to output format. I feel your proposal is reasonable. So it would be nice if we can implement it in future! |
tk0miya
added
extensions:autodoc
type:proposal
Fixes "WARNING: more than one target found for cross-reference". Actually Sphinx authors seem to agree that in the case we are running into, Sphinx should prefer the type from the current module. But this is not implemented yet: sphinx-doc/sphinx#4961.
Fixes "WARNING: more than one target found for cross-reference". Actually Sphinx authors seem to agree that in the case similar to the one that we are running into, Sphinx should prefer the type from the current module. But this is [not implemented yet]( sphinx-doc/sphinx#4961).
|
hi there! i'm curious about this thread as i'm running into a similar issue with a pr for nbconvert . what is weird is that it's throwing warnings only in circleCI not in my local build and also on pages that are just text but have api content below such as this page. and it's not throwing warnings (treated as errors) each run, it throws ONE of them and quits. then i fix it and another pops up. Does anyone have a suggestion regarding how to treat these warnings by chance? @tk0miya it would be wonderful to have a clean CI build. |
|
Is there any workaround at the moment? I have classes with the same name in different modules in my project and I get the error (removed acutal names): Am I forced to rename the classes now or is there a way to ignore this particular situation? |
|
On my project, the doc builds correctly for Sphinx 3.x and fails (because warnings treated as errors) on 4.x. I'll need to stay on 3.x until it's resolved, but if you have an idea where to look for, I can try poking and see if I find a fix :) |
|
This bug out of no where has started impacting us from yesterday https://github.com/abhinavsingh/proxy.py/runs/4836507299?check_suite_focus=true It all started after we add a file named |
|
@ewjoachim Yep, that worked. When can we expect the next release (or pre-release). We'll need to remove the diff below at some point. diff --git a/docs/requirements.in b/docs/requirements.in
index 24f2e03..263030d 100644
--- a/docs/requirements.in
+++ b/docs/requirements.in
@@ -1,6 +1,6 @@
myst-parser[linkify] >= 0.15.2
setuptools-scm >= 6.3.2
-Sphinx >= 4.3.0
+Sphinx @ git+https://github.com/ewjoachim/sphinx@py-domain-canonical-any-10088
furo >= 2021.11.15
sphinxcontrib-apidoc >= 0.3.0
sphinxcontrib-towncrier >= 0.2.0a0 |
Sorry bad news is that CI still failed , ref https://github.com/abhinavsingh/proxy.py/runs/4844619931?check_suite_focus=true Unfortunately, I am not sure about our setup either. There is a |
|
Update: Looks like we cannot try the patch out until release. Other CI runs starts to throw Latest run https://github.com/abhinavsingh/proxy.py/runs/4845237618?check_suite_focus=true We are also seeing newer
|
See sphinx-doc/sphinx#4961. Revert this change when resolved.
|
@rmorshea: Your Sadly, I incorrectly assumed Sphinx resolved relative references against the current module out-of-the-box and then documented a several thousand-line runtime type-checker under that assumption. Several hundred I'm now furiously canonicalizing all relative references into absolute references. Since this is terrible, I find myself pounding the keyboard repeatedly. Is there really no sane solution for this four year-old issue in 2022? This should really just work by default: from some_package import MyClass
def my_function():
'''Uses :class:`MyClass`'''EDIT: We gave up on canonicalizing all relative references into absolute references. Instead, we just ruthlessly silenced all several hundred warnings with a trivial workaround shamelessly pilfered from @RDFLib: # List of zero or more Sphinx-specific warning categories to be squelched (i.e.,
# suppressed, ignored).
suppress_warnings = [
#FIXME: *THIS IS TERRIBLE.* Generally speaking, we do want Sphinx to inform
#us about cross-referencing failures. Remove this hack entirely after Sphinx
#resolves this open issue:
# https://github.com/sphinx-doc/sphinx/issues/4961
# Squelch mostly ignorable warnings resembling:
# WARNING: more than one target found for cross-reference 'TypeHint':
# beartype.door._doorcls.TypeHint, beartype.door.TypeHint
#
# Sphinx currently emits *HUNDREDS* of these warnings against our
# documentation. All of these warnings appear to be ignorable. Although we
# could explicitly squelch *SOME* of these warnings by canonicalizing
# relative to absolute references in docstrings, Sphinx emits still others
# of these warnings when parsing PEP-compliant type hints via static
# analysis. Since those hints are actual hints that *CANNOT* by definition
# by canonicalized, our only recourse is to squelch warnings altogether.
'ref.python',
]That'll do, Sphinx. That'll do. |
This commit is the next in a commit chain reconfiguring Sphinx of what will hopefully be the final nail in the lackluster coffin that is our Sphinx configuration, en-route to resolving issue #8 (!) kindly submitted a literal lifetime ago by visionary computer vision export and long-standing phenomenal Finn @felix-hilden (Felix Hildén). Specifically, this commit ruthlessly circumvents the upstream sphinx-doc/sphinx#4961 issue causing Sphinx to emit literally hundreds of ignorable warnings resembling ``"WARNING: more than one target found for cross-reference 'TypeHint': beartype.door._doorcls.TypeHint, beartype.door.TypeHint"`` with a [trivial circumvention shamelessly pilfered from @RDFLib](https://github.com/RDFLib/rdflib/blob/3a418218d6bcdb46f78342e14c024063e2f53e71/docs/conf.py#L255). (*Unacceptable scepter of powdered pewter!*)
|
@leycec if there's interest, I'd be willing to update the package. I just merged some minor updates (unreleased) but it's hard to know if I've covered all the edge cases that people may have in their own projects. |
|
@rmorshea would you be interested in merging it to the Sphinx core? A |
|
That would be great. Though, it would be useful if someone more familiar with Sphinx took a look at it to see if all the heuristics I came up with make sense. It's also not the cleanest code I've ever written, so it might require some work on my end to clean things up a bit before that review. |
|
Hi @rmorshea, I came across this issue as I am affected myself and across your extension. I gave it a try, simply pulled the source into my venv as I wanted to try the latest updates. ;-) However, as soon as I activate this extension I get additional warnings on my builds while the cross-reference warnings still persist. My new warnings look like this: The question is, what does this mean? My structure:
My Env:
@AA-Turner
So this is fairly simple in terms of complexity. My expectation would be, that Sphinx sees this docstring reference, tries to find Kind regards, Martin |
|
Hey @martinpakosch, I made an issue in my repository where I'll answer this question. For others who have questions specifically about my extension it seems like it would be best to post an issue there rather than in this thread. |
|
Cool, thx @rmorshea. Was not able to create it directly due to the previous "archive" state of your repo. :D |
See sphinx-doc/sphinx#4961 Change-Id: Ic545c5ba8cf853f784587a4acca4664fddf80846
This minor release expands the infinitely vast (yet mostly empty) universe of @beartype into the hitherto uncharted realms of **configuration,** **exception identification,** **Nuitka,** **`typing.NamedTuple`,** and **Python 3.11.** Also, other things were done. We swear it! This minor release resolves **16 issues** and merges **2 pull requests.** Noteworthy changes include: ## Compatibility Improved. * **Python 3.11.** This is the first @beartype support to officially support the recently released Python 3.11. Notably, this release: * Synchronizes our public `beartype.typing` subpackage against upstream changes in the standard `typing` module introduced in Python 3.11. * Supports PEP-compliant type hints subscripted by the empty tuple (e.g., `typing.Tuple[()]`), whose low-level implementation fundamentally changed under Python 3.11. * Updates our GitHub Actions-based continuous integration (CI) workflow to exercise @beartype against Python 3.11. * **Nuitka.** This is the first @beartype release to officially support Nuitka (i.e., the increasingly popular Python compiler that stuns us all), resolving feature request #197 kindly submitted by @shenwpo (also known as the giant flaming metallic letter e). This includes a new `test_nuitka()` integration test showing that Nuitka successfully compiles a minimal-length example (MLE) runtime type-checked by @beartype. * **`typing.NamedTuple`.** This release adds support for deeply type-checking subclasses of the PEP 484-compliant `typing.NamedTuple` superclass. Specifically, this release improves the resiliency of our PEP 563 resolution mechanism (i.e., the public `beartype.peps.resolve_pep563()` function) against callables whose `__module__` dunder attributes lie. This includes *all* `typing.NamedTuple` subclasses, which synthesize callables whose `__module__` dunder attributes erroneously claim to reside in the non-existent `"namedtuple_Foo"` module. Doing so resolves issue #181 kindly submitted by probably ingenious "Probabilistic Machine Learning" author @murphyk (Kevin P. Murphy). ## Features Added * **Beartype configuration API.** This release publishes a new public API for externally configuring @beartype via the now-official `beartype.BeartypeConf` type and `beartype.BeartypeStrategy` enumeration. Specifically, this release adds: * **`beartype.BeartypeConf.is_color`,** a new tri-state boolean enabling end users to control how and whether beartype colours **type-checking violations** (i.e., :class:`beartype.roar.BeartypeCallHintViolation` exceptions) with POSIX-compliant ANSI escape sequences for readability, resolving issue #178 kindly submitted by the foxy ZeroGuard and River Oakfield founder @foxx (Cal Leeming). Rejoice, typing acolytes, for you have now been freed from the prismatic shackles of the rainbow! * **`beartype.BeartypeConf.is_pep484_tower`**, a new standard boolean enabling end users to control whether @beartype supports the [implicit numeric tower standardized by PEP 484](https://peps.python.org/pep-0484/#the-numeric-tower) or not, resolving issue #174 kindly submitted by dashing French Canadian @felixchenier (Félix Chénier). * **`beartype.BeartypeStrategy.O0`**, a new **no-time strategy** (i.e., beartype configuration option generalizing the standard `@typing.no_type_check` decorator). Enabling this strategy instructs the `@beartype` decorator to recall and preserve previously applied no-time strategies; internally, `@beartype` detects and reduces configurations resembling `conf=BeartypeConf(strategy=BeartypeStrategy.O0, ...)` to the `@typing.no_type_check` decorator. Users may now blacklist specific callables from being type-checked by configuring this strategy as documented in our front-facing `README.rst` documentation... *somewhere.* It's in there somewhere, people. * **Beartype exception API.** This release publishes a new public API for externally identifying the cause of **type-checking violations** (i.e., instances of the `beartype.roar.BeartypeCallHintViolation` exception class) raised by @beartype. These exceptions now publicly expose the user-defined objects responsible for those violations via a new `BeartypeCallHintViolation.culprits` property, resolving feature request #180 kindly submitted by @Jasha10 the Supremely Patient and Understanding GitHubber. For safety, this property dynamically returns a non-empty tuple of the one or more responsible culprits defined as either: * For each culprit that supports weak references and is still alive (i.e., has yet to be garbage-collected), that culprit as is. * Else, the machine-readable string representation of that culprit truncated to a reasonable number of characters. ## Features Deprecated * **`beartype.roar.BeartypeAbby*Exception`.** This release deprecates all lingering remnants of the prior `beartype.abby` subpackage – including: * `beartype.roar.BeartypeAbbyException`, supplanted by `beartype.roar.BeartypeDoorException`. * `beartype.roar.BeartypeAbbyHintViolation`, supplanted by `beartype.roar.BeartypeDoorHintViolation`. * `beartype.roar.BeartypeAbbyTesterException`, supplanted by `beartype.roar.BeartypeDoorException`. ## Static Type-checking Improved * **@beartype exports.** This release terminally pacifies: * Mypy by publicizing all exported attributes from the top-level `beartype` package via a new `beartype.__all__` dunder attribute. Thanks to the stylishly pink-haired @pinkwah (Zohar Malamant) for the rapid pull request (PR). * `pyright` by explicitly re-exporting all public attributes of the top-level `beartype` package, resolving issue #169 kindly submitted by MIT AI mastermind @rsokl (Ryan Soklaski). * **Continuous integration (CI).** This release integrates our GitHub Actions-based continuous integration (CI) workflow (i.e., `.github/workflows/python_test.yml`) with third-party GitHub Actions statically type-checking beartype against both `mypy` and `pyright` at CI time – including on every commit as well as pull request (PR). For both robustness and efficiency, this release prevents functional tests in our test suite that perform these same static type-checks from running under CI. Doing so resolves a furious spate of spurious CI complaints. So what we did there? We rhymed. Notably, this release: * Leverages @jakebailey's superb `jakebailey/pyright-action` action to exercise @beartype against `pyright` at CI time. * Manually installs and runs `mypy` in a low-level manner under CI *without* leveraging @jpetrucciani's otherwise stellar `jpetrucciani/mypy-check` action -- which @beartype hopes to revisit at a later date when the issue tracker settles there a bit. Thanks so much, @jpetrucciani! You dah real QA MVP. ## Issue Resolved * **`beartype.door.TypeHint` comparisons.** This release significantly improves the robustness of comparison operators overloaded by the object-oriented `beartype.door.TypeHint` API, resolving issue #198 kindly submitted by @wesselb the phenomenal Amsterdammer of [Plum](https://github.com/wesselb/plum) fame. This includes edge cases when: * Comparing unions against both other unions *and* non-unions (e.g., `typing.Any`, isinstanceable classes). * Comparing tuple type hints against `typing.Any`. * **`beartype.BeartypeConf` caching.** This release resolves a critical (yet ultimately trivial) caching issue with respect to `beartype.BeartypeConf` singletons, in which singletons initialized with different parameters could conceivably have been erroneously cached to the same object. Hash collisions! I see hash collisions everywhere! * **Call stack iteration robustness.** This release resolves an edge case in our private `beartype._util.func.utilfuncframe.iter_frames()` generator iterating over stack frames on the current call stack. Specifically, this generator now safely reduces to the empty generator (i.e., noop) when the caller requested that generator ignore more stack frames than exist on the call stack. Although raising an exception would also be feasible, doing so would only needlessly increase the fragility of this already fragile mission-critical generator. ## Documentation Resolved * **Broken anchor links.** This release repairs broken anchor links dotted throughout our monolithic `README.rst` to actually point to valid (sub)sections. * **Sphinx configuration.** This release reconfigures the lackluster coffin that is our Sphinx configuration, en-route to resolving issue #8 (!) kindly submitted a literal lifetime ago by visionary computer vision export and long-standing phenomenal Finn @felix-hilden (Felix Hildén). Specifically, this release: * **Enables Furo,** switching from the default Read The Docs (RTD) Sphinx theme to the third-party Furo theme. We selected this theme according to mostly objective (albeit ultimately subjective) heuristic criteria. In descending order of importance, we selected the theme with: 1. The most frequent git commit history. 2. The open issues and pull requests (PRs). 3. The most GitHub stars as a crude proxy for aggregate rating. Furo handily bested all other themes across all three criteria. Furo is very well-maintained, frequently closes out open issues and merges open PRs, and sports the highest quantity of GitHub stars by an overwhelming margin. `\o/` * **Enables the builtin `intersphinx` extension,** enabling attributes defined by the standard library (e.g., the `typing` module, the `types.GenericAlias` type) to be cross-referenced as a fallback when *not* already defined by this project. * **Reconfigures RTD** through our top-level `.readthedocs.yml` configuration to: * Build under the most recent Long Term Service (LTS) release of Ubuntu. * Build under the most recently released minor version of CPython. * Configure Sphinx via our `doc/source/conf.py` script. * **Restores the standard `sys.path` hack** – which, for unknown reasons, @leycec disabled but thankfully left commented out. Doing so re-resolves issue #120, kindly submitted by @kloczek (Tomasz Kłoczko) five friggin' months ago. Thanks so much for the fast patch and rapid turn-around, @kloczek! * **Improves pathname robustness** by intelligently detecting documentation paths via the standard `pathlib.Path` API. * **Enables `autoapi`.** This release successfully transitions from Sphinx's builtin (but insane) `autodoc` and `autosummary` extensions to Read The Doc (RTD)'s non-builtin (but sane) `autoapi` extension. * **Adds a local URI store** (i.e., hidden reStructuredText (reST) document centralizing common URI links in reST format, automatically exposed to all other reST documents in this project via the `rst_epilog` setting in `conf.py`) at `doc/src/_links.rst`. * **Removes obsolete cruft,** which accrues with time like entropic motes in God's eye. That was a reference to a Golden Age of Scifi book, people! Don't ask why God only has one eye. It's better not to contemplate these matters. * **Ruthlessly circumvents upstream issue sphinx-doc/sphinx#4961,** causing Sphinx to emit literally hundreds of ignorable warnings resembling ``"WARNING: more than one target found for cross-reference 'TypeHint':`` ``beartype.door._doorcls.TypeHint, beartype.door.TypeHint"`` with a [trivial circumvention shamelessly pilfered from @RDFLib](https://github.com/RDFLib/rdflib/blob/3a418218d6bcdb46f78342e14c024063e2f53e71/docs/conf.py#L255). ## Documentation Added * **[Beartype Object-oriented API](https://github.com/beartype/beartype/tree/76aebd63b5f32ac6bdab6420eb0c9bfa2ca09b29#id36).** This release prefaces our "Beartype Object-oriented API" subsection with a human-readable discussion of the Decidedly Object-Oriented Runtime-checking (DOOR) – also known as "That API Which Breaks Hearts and Minds Alike." * **[Procedural Showcase]**(https://github.com/beartype/beartype/#procedural-showcase). This release adds a new *Procedural Showcase* subsection containing a new *Detect API Breakage* subsubsection exhibiting a real-world usage for our recently published `beartype.door.is_subhint()` tester: detecting API breakage across the type hints annotating arbitrary callables in exactly ten lines of code. * **[Near-real-time FAQ entry](https://github.com/beartype/beartype/#beartype-realtime).** This release adds a new FAQ entry entitled *What does "near-real-time" even mean?*, justifying our recent categorization of @beartype as a "near-real-time runtime type-checker." Let's pretend @leycec knows what he's talking about. * **[JAX, Numpy, and PyTorch FAQ entries](https://github.com/beartype/beartype/#jax-arrays).** This release expands our existing FAQ with entries on typing JAX and NumPy arrays and PyTorch tensors to highlight the stupefying potential unlocked by the third-party `jaxtyping`, `nptyping`, and TorchTyping packages, resolving issue #98 submitted a literal lifetime ago by Edinburgh NLP researcher @amitkparekh (Amit Parekh). * **[VSCode FAQ entry](https://github.com/beartype/beartype/tree/76aebd63b5f32ac6bdab6420eb0c9bfa2ca09b29#id28).** This release rewrites our entire FAQ entry on `pyright` + Pylance + VSCode to be significantly more charitable towards `pyright`, resolving issue #170 kindly submitted by MIT AI mastermind @rsokl (Ryan Soklaski). * **[Type narrowing FAQ entry](https://github.com/beartype/beartype/tree/76aebd63b5f32ac6bdab6420eb0c9bfa2ca09b29#id30).** This release adds a new FAQ entry on type narrowing, strongly inspired by (*...wait for it*) MIT AI mastermind @rsokl (Ryan Soklaski)'s equally masterful writing at issue #166. (*Powerful bowers full of flowers!*)
|
@AA-Turner @rmorshea Any thoughts on progressing a merge of this code? |
|
What solved this issue for me is setting the following autodoc option in |
- set `ignore-module-all` for `autodoc_default_options` to resolve some Sphinx errors about duplicate / ambiguous references sphinx-doc/sphinx#4961 (comment) - Standardize some non-standard (Google-ish) docstrings to Sphinx format, to avoid ruff and Sphinx arguing about underline length. - Fix indents and other minor whitespace / formatting changes.
Fixes python-semantic-release#1029 - set `ignore-module-all` for `autodoc_default_options` to resolve some Sphinx errors about duplicate / ambiguous references sphinx-doc/sphinx#4961 (comment) - Standardize some non-standard (Google-ish) docstrings to Sphinx format, to avoid ruff and Sphinx arguing about underline length. - Fix indents and other minor whitespace / formatting changes.
set `ignore-module-all` for `autodoc_default_options` to resolve some Sphinx errors about duplicate / ambiguous references sphinx-doc/sphinx#4961 (comment) Standardize some non-standard (Google-ish) docstrings to Sphinx format, to avoid ruff and Sphinx arguing about underline length. Fix indents and other minor whitespace / formatting changes. Fixes #1029
it might be a bug of autoapi: sphinx-doc/sphinx#4961 (comment)
Subject: more than one target found for cross reference should prefer current file's method over other libraries methods
Problem
The expected one is clear: The one from current file interwiki_graph should be preferred over the imported, but Sphinx still throwns a warning.
Procedure to reproduce the problem
Build HTML of Pywikibot (last build by us: https://integration.wikimedia.org/ci/job/pywikibot-core-tox-publish/424/console) or try to simulate the situation
Error logs / results
Expected results
It should prefer the current file over the imported one
Reproducible project / your project
Environment info
The text was updated successfully, but these errors were encountered: