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.