Add suppress warning type for any `'myst' reference target not found`

[jaymegordo]

The following warning:

../../CONTRIBUTING.md:4: WARNING: 'myst' reference target not found: README.md

doesn't seem to be raised in the same was as other myst warnings, eg doesn't have [myst.header] at the end of the warning.

To Reproduce

Steps to reproduce the behavior:

1. Create markdown document with a reference to root level readme eg [README](README.md)
2. Add suppress_warnings = ['myst.reference'] to sphinx conf.py
3. Build docs with sphinx

Expected behavior

Would be nice to suppress any warning by any arbitrary text.

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
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).
Welcome to the EBP community! :tada:

[chrisjsewell]

heys @jaymegordo could you provide a minimal working example to reproduce this warning, i.e. it seems like you have something like this

docs/source/conf.py
    extensions = ["myst_parser"]
docs/source/index.md
    content?
CONTRIBUTING.md
    # Heading

    [README](README.md)
README.md
    # Heading

[vineetsharma883]

I have following folder structure:-

automation_p/
    |_____worfklow.md
    |_____Conditional.sh
docs/
    |____source
    |     |_____conf.py
    |     |_____index.rst
    |_____build

Following is problematic line in workflow.md -

...
...
to check the condition ref [Conditional.sh](./Conditional.sh)
...
...

On running make html, I am getting following error - WARNING: 'myst' reference target not found: ./Conditional.sh

[choldgraf]

I believe that the issue here is that .sh files are not supported by Sphinx, and so it cannot find it. If you want to link to a raw file, use {download}`./Conditional.sh <Conditional.sh>`

[arwedus]

I guess that the need of the original author is to suppress these warnings, not to fix the issue itself. I have the same request.

I include some files in the Sphinx documentation which are targeted at people who navigate the source code in an IDE or in a github or Bitbucket GUI. I include links to certain files which should not be copied to the documentation output, e.g. a header file or source file, to support easy navigation in the code.

The warnings we get are along the lines of:

/home/user/workspace/package/README.md:13: WARNING: 'myst' reference target not found: ./CMakeLists.txt
/home/user/workspace/package/README.md:13: WARNING: 'myst' reference target not found: ./src/main.cpp
/home/user/workspace/package/README.md:13: WARNING: 'myst' reference target not found: ./test/excluded-document.md

Wanted behavior: Just remove the link and output the text (if available) or the link.

ideally, all files which are excluded or have different file extension (e.g. .txt, .cpp, .h, .xml) do not raise a warning, while others do.

[arwedus]

@chrisjsewell : Are you still actively working on MyST-parser? I have not seen much activity of you since the last release (1.5.2 End of August). This topic is still important to us. Who will pick up the development?

[chrisjsewell]

Are you still actively working on MyST-parser?

Yes, but I'm afraid this is just not a priority fix for myself, since it is not it is not keeping with sphinx itself: you cannot reference arbitrary files with sphinx doc/any roles, only parsed files. As noted by @choldgraf, you can use roles like download to do this

I think you can probably suppress all reference warnings, I don't know off-hand what the warning type is (it would be nice is sphinx itself provided these like myst does, but unfortunately they don't https://github.com/sphinx-doc/sphinx/issues/8845)

[chrisjsewell]

Naturally, we are happy to receive PRs with proposals to add such features

[john-hen]

I think the problem here is that a warning is raised in the first place, not to suppress it. And it's because the syntax is ambiguous. We can do `Conditional.sh <./Conditional.sh>`_ in reStructuredText and would expect this to be the same as [Conditional.sh](./Conditional.sh) in Markdown. No Sphinx roles involved whatsoever. Of course, if the link target is a source file, such as ReadMe.md, then MyST should try to resolve that reference, so it acts like the any role. But this is not a problem in reST/Sphinx itself.

[choldgraf]

An issue here is that Sphinx only copies over the files that are explicitly included as a part of the document model, so if you did [mylink](some-file.txt), then when your documentation HTML is built, there's no guarantee that some-file.txt will be there to link to in your docs. The {download} role will cause a copy to happen for the target file, so that it's included with the assets in your outputs.

So it's a bit more complex than just telling Sphinx not to raise a warning if the file is not a source file.

That said, I'm surprised that this works in rST. What happens? Does it not throw a warning, but that link is then broken in the final output?

[john-hen]

I agree that the use case is somewhat esoteric. But I just happened to answer a question on SO today where the user was asking for a way around the download role. And there is a way. We can use html_extra_path to have Sphinx copy over files, at least to the root folder. I guess I must have used something like that myself at some point. Though not sure about the exact use case of the other commenters in this thread. It's not really clear to me either how those files get there.

It should also work with folders named in html_static_path, but I haven't looked into that.

[arwedus]

I think the problem here is that a warning is raised in the first place, not to suppress it. And it's because the syntax is ambiguous. We can do `Conditional.sh <./Conditional.sh>`_ in reStructuredText and would expect this to be the same as [Conditional.sh](./Conditional.sh) in Markdown. No Sphinx roles involved whatsoever. Of course, if the link target is a source file, such as ReadMe.md, then MyST should try to resolve that reference, so it acts like the any role. But this is not a problem in reST/Sphinx itself.

Exactly! In rST there's a difference between a file you just link to (i.e. my source file <../src/main.cpp>`_) and documents you refer to (i.e. :doc:'index'). rST won't check plain links and just don't care. The use case for this is to refer to some files in the same repo, and the links are navigatable e.g. via an rST viewer in VS Code or on github.

In Markdown, I just have links, whether it's [other doc](path/to/other_doc.md) or [my source file](../src/main.cpp). apparently, MyST tries to transform all markdown links to :doc: references.

The issue pops up here since we want to include already existing Markdown documents with our developer documentation in sphinx - and they are full of links to source files etc.

@chrisjsewell : Anyhow, I'm happy and relieved to read that MyST Parser is still under active development / maintainance and you would be willing to review PRs. Very good 👍🏼 keep up the good work.

[mara004]

Which warning type do I need to suppress to hide 'myst' reference target not found and Unknown target name warnings?

[ravindk89]

@mara004 what worked for me is:

suppress_warnings = [ 'ref.myst']

[mara004]

Thanks!