You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In a file called df.md, we want to cross-reference the orm label, which is in a file orm.md, next to df.md, like
(orm)=
# CrateDB and ORM libraries
When doing it using MyST linking, in either of that form,
<project:#orm>[](#orm)
we are receiving the venerable ambiguity warning, which is an error in our case, because we are exclusively using Sphinx with -W --keep-going :
Warning, treated as error:
/path/to/docs/connect/df.md:16:more than one target found for 'myst' cross-reference orm:
could be :std:ref:`CrateDB and ORM libraries` or :std:doc:`CrateDB and ORM libraries`
However, we have not been able to find any notation to satisfy the MyST parser, in both directions, either trying to be more explicit to reference std:ref:, or std:doc:. Do you have any hints how to make it work?
Workaround
It works well when using the {doc} / {ref} syntax, apparently, well, because it is explicit by design?
{doc}`orm`\
{ref}`orm`
Expected Behavior
Documentation or Bug?
Having a documentation sample ready at Reference Roles, about how to resolve that situation with MyST linking.
Fixing an eventual bug, if there is an underlying flaw, or documenting it.
Thoughts
Regarding the handling of invalid references, it would be sweet if any of the applicable features to suppress warnings about myst.xref_ambiguous could be made work per-page through a corresponding front matter. We have not been able to make it work. If you can confirm, and agree, this item should probably make it into a separate issue?
---
# [](#orm) is ambiguous, because it refers to both a page and a label.# Accept the ambiguity on this page, so that Sphinx will not error out.suppress_warnings: ["myst.xref_ambiguous"]myst-suppress-warnings: ["myst.xref_ambiguous"]
---
To Reproduce
Trivia: Within a file called orm.md, there is a reference label also called orm. C'est la vie.
orm.md
(orm)=
# CrateDB and ORM libraries
df.md
<project:#orm>\[](#orm)
The text was updated successfully, but these errors were encountered:
Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
We have not been able to find any notation to satisfy the MyST parser, trying to link to the orm reference, in both directions, either trying to be more explicit to reference std:ref:, or std:doc:. Do you have any hints how to make it work?
What version of
myst-parser
are you using?2.0.0
What version dependencies are you using?
$ python -c "import myst_parser; print(myst_parser.__version__)" 2.0.0
$ python -c "import docutils; print(docutils.__version__)" 0.20.1
$ python -c "import sphinx; print(sphinx.__version__)" 7.2.6
What operating system are you using?
Mac
Describe the Bug
Problem
In a file called
df.md
, we want to cross-reference theorm
label, which is in a fileorm.md
, next todf.md
, like(orm)= # CrateDB and ORM libraries
When doing it using MyST linking, in either of that form,
we are receiving the venerable ambiguity warning, which is an error in our case, because we are exclusively using Sphinx with
-W --keep-going
:However, we have not been able to find any notation to satisfy the MyST parser, in both directions, either trying to be more explicit to reference
std:ref:
, orstd:doc:
. Do you have any hints how to make it work?Workaround
It works well when using the
{doc}
/{ref}
syntax, apparently, well, because it is explicit by design?Expected Behavior
Documentation or Bug?
Thoughts
Regarding the handling of invalid references, it would be sweet if any of the applicable features to suppress warnings about
myst.xref_ambiguous
could be made work per-page through a corresponding front matter. We have not been able to make it work. If you can confirm, and agree, this item should probably make it into a separate issue?To Reproduce
Trivia: Within a file called
orm.md
, there is a reference label also calledorm
. C'est la vie.orm.md
(orm)= # CrateDB and ORM libraries
df.md
The text was updated successfully, but these errors were encountered: