sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.59k stars 2.12k forks source link

3.3.0 linkcheck incorrectly reports _static links as broken #8374

Closed dHannasch closed 4 years ago

dHannasch commented 4 years ago

Describe the bug Links to static files such as

`local mirror <_static/docs_mirror/index.html>`_

are erroneously reported as broken by

python -m sphinx -b linkcheck

like so:

(line    9) broken    _static/docs_mirror/index.html - 

Checking these links by clicking on them manually reveals that they work fine, so the problem is not with the Sphinx core, just with the linkcheck.

To Reproduce Steps to reproduce the behavior:

python -m sphinx -b linkcheck

$ git clone https://github.com/.../some_project
$ cd some_project
$ pip install -r requirements.txt
$ cd docs
$ make html SPHINXOPTS="-D language=de"
$ # open _build/html/index and see bla bla

Expected behavior Links that work should be reported as ok by the linkcheck.

Your project Link to your sphinx project, or attach zipped small project sample.

Environment info

Additional context Technically, 3.2.1 also reports the links as 'broken' when you run the linkcheck. It is currently unknown how many versions back this has been happening. What has changed is that now sphinx -b linkcheck returns an error code. Funnily enough, 3.2.1 erroneously reports the links as broken but does not erroneously return an error code.

Interestingly, 3.2.1 linkcheck does return an error code when other kinds of links are broken, but it appears to (wisely) always ignore "broken" links to static files.

tk0miya commented 4 years ago

I guess linkcheck could not find _static/docs_mirror/index.html on your project. So it is marked as broken. How do you copy _static/docs_mirror/index.html?

dHannasch commented 4 years ago

Never mind, the docs were getting built differently in the pages job than in the testing job. The way they were getting built in the testing job, the static files really weren't included due to lack of https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path. They've probably been doing that for years and I never noticed since prior to 3.3.0 the test passed despite the links being (in the testing environment) broken.

_static/docs_mirror/index.html was just an example I copied from https://stackoverflow.com/questions/38281486/how-to-create-link-to-local-index-html-from-sphinx-documentation. The plan was to make a stripped-down simple reproduction package based on that, but when I tried to make a stripped-down simple reproduction package, the crash evaporated.