Warnings for relative links to other documents

[asmeurer]

I am getting warnings building my site like:

$ make html
Running Sphinx v1.8.3
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 7 added, 0 changed, 0 removed
/Users/aaronmeurer/anaconda3/lib/python3.6/site-packages/recommonmark/parser.py:65: UserWarning: Container node skipped: type=document
  warn("Container node skipped: type={0}".format(mdnode.t))
reading sources... [100%] usage
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] usage
/Users/aaronmeurer/Documents/brown-water-python/docs/helper-functions.md:4: WARNING: None:any reference target not found: usage.html
/Users/aaronmeurer/Documents/brown-water-python/docs/helper-functions.md:189: WARNING: None:any reference target not found: alternatives.html
/Users/aaronmeurer/Documents/brown-water-python/docs/helper-functions.md:267: WARNING: None:any reference target not found: intro.html
/Users/aaronmeurer/Documents/brown-water-python/docs/intro.md:142: WARNING: None:any reference target not found: alternatives.html
/Users/aaronmeurer/Documents/brown-water-python/docs/usage.md:150: WARNING: None:any reference target not found: tokens.html
/Users/aaronmeurer/Documents/brown-water-python/docs/usage.md:305: WARNING: None:any reference target not found: examples.html
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 6 warnings.

The HTML pages are in _build/html.

The warnings are coming from relative links to other pages, like [link](page.html). The links in the final site seem to work fine.

It used to build fine, so something broke. I don't know if the UserWarning is related.

[tpatnoe]

I am seeing the same thing. I usually run with sphinx option -W to turn warnings into errors. This is very useful to keep clean documentation.

The relative links which warning and then error are *.md or *.rst files which eventually are converted into *.html.

Perhaps check for *.md or *.rst equivalent for missing HTML files.

[tpatnoe]

Rolling back to version 0.4.0 of recommonmark still logs a warning but doesn't stop the build.

[asmeurer]

It seems I forgot to mention here, changing the link from [link](page.html) to [link](page.md) makes the warning go away. But then the link in the rendered page doesn't have any Markdown formatting! Markdown formatting in links is one of the reasons I'm using recommonmark in the first place, instead of normal Sphinx with RST.

I also use html: SPHINXOPTS += -W in my Makefile, as warnings in Sphinx tend to be things that you want to fix, but I've had to disable it because of this bug.

[gibfahn]

What happens if you do [link](page.html) -> [link](page)?

[asmeurer]

@gibfahn looks like it's the same as [link](page.md). It removes the warning and the link works, but it removes all the formatting from the link text.

[drrosa]

Changing the link from [link](page.html) to [link](page.md) makes the warning go away. But then the link in the rendered page doesn't have any Markdown formatting! Markdown formatting in links is one of the reasons I'm using recommonmark in the first place, instead of normal Sphinx with RST.

I also use html: SPHINXOPTS += -W in my Makefile, as warnings in Sphinx tend to be things that you want to fix, but I've had to disable it because of this bug.

@asmeurer I'm not seeing any rendering problems when I try this, but what exactly do you mean by "it removes all the formatting from the link text"?

Are you saying that something like **[formatting](page.md)** would end up with its bold formatting removed and rendered as "formatting" instead?

[asmeurer]

Yes, except I use rendering inside the link, like [`code`](page.md). I haven't tried moving it outside the link.

[drrosa]

Oh, I see. Yeah, the formatting inside the link text doesn't work unless it's an .html link. Formatting outside of an .md link definitely works though.

Hint: I also noticed that .html links with an #anchor don't trigger those Warnings. So you could add an anchor to links where you want to have code formatting. i.e. [`code`](page.html#dummy-anchor)

[caspar-ai]

Are there any plans to fix this issue? I am still seeing it on Sphinx==2.3.1 and recommonmark==0.6.0.

Specifically linking to a pre-built HTML document from inside a markdown file produces a warning during the sphinx build. We use it when we reference the output from a doxygen build, although you can reproduce with any local HTML reference.

I have tried all the different suggestions above and none work, specifically:

• [link](./test.html) <- The one I would expect to work
• [link](test.html)
• [link](./test)
• [link](test)
• [link](./test.md)

All produce a warning similar to this:

/cdh/test.md:3: WARNING: None:any reference target not found: ./prebuilt.html

@drrosa is correct that adding the #anchor makes the warning go away, but that appears to be because it suppresses all checks, i.e. if not_there.html actually doesn't exist, then the following will not produce an error:

[link](./not_there.html#dummy-anchor)

Which means that enabling warnings becomes once again meaningless to catch broken / stale internal references.

(P.S. I think the last post suggested this wasn't an issue except for losing formatting - I don't have any formatting concerns, just a plain old link is fine - so perhaps two separate issues here?)

[stefanv]

We are trying to link to a static .json file from a document, and are seeing the same:

user_guide.md:262: WARNING: None:any reference target not found: data/example.json

[asmeurer]

FWIW, I've switched from recommonmark to MyST https://myst-parser.readthedocs.io/en/latest/. It is very similar to recommonmark (Markdown syntax with Sphinx), but unlike recommonmark, it adds some syntax to do cross-references, so that issues like this aren't a problem (you can do real cross-references which are checked by Sphinx).

[balopat]

Same thing happens with relative paths targeting .ipynb files - interestingly, if I remove the extension, it works 🤔, but that breaks Github's linking. I agree @asmeurer, MyST seems to do a good job with minimal overhead to switch.