linkcheck could also check local (internal) links

[anntzer]

Subject: linkcheck currently doesn't check local (internal) links, but this would be useful.

Problem

See above.

Procedure to reproduce the problem

Create a template project with sphinx-quickstart, put the following in index.rst

broken external-link_
broken local-link_

.. _external-link: https://lkfqhlkghflkhs
.. _local-link: doesntexist

Run make linkcheck

Error logs / results

Running Sphinx v1.7.6
making output directory...
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [linkcheck]: targets for 1 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [100%] index                                                                   
(line   14) -local-   doesntexist
(line   14) broken    https://lkfqhlkghflkhs - HTTPSConnectionPool(host='lkfqhlkghflkhs', port=443): Max retries exceeded with url: / (Caused by NewConnectionError('<urllib3.connection.VerifiedHTTPSConnection object at 0x7faed7ddfc88>: Failed to establish a new connection: [Errno -2] Name or service not known',))

build finished with problems.
make: *** [Makefile:20: linkcheck] Error 1

Expected results

Also a check for the local link.

Reproducible project / your project

N/A

Environment info

• OS: Arch Linux
• Python version: 3.6
• Sphinx version: 1.7.6

[tk0miya]

+0: It might be useful. But all we can check is only inside sphinx-document. If users copy extra file in deploy script, we'll misdetect broken links. And it is hard if local hyperlink is absolute path. We don't know where the document will be placed.

[anntzer]

At least this could be an optional feature; I'd guess there are a lot of sphinx deployments which do not add anything manually and just stick to what sphinx generates.

[tk0miya]

Agreed. I also believe it is useful.

[westurner]

https://github.com/sphinx-doc/sphinx/pull/7103/files#diff-bb67587af94a24f53692228ea27061edR252 at least includes the local link in the json output

[Martiix]

Is there any updates to this issue? Could use a local linkchecker in my sphinx docs.
Also, links to headlines should also appear in the linkchecker as local links.
Links such as : 2D <#2d-image>__ does not appear, and doesn't seem to be working due to it starting with a number.

[tk0miya]

It seems nobody sends a PR for us. How about you? It's time to contribute :-)

[jli]

Apologies if this is a bit off-topic, but I noticed that linkcheck is reporting broken links for all my local links. I suspect it's due to a problem with how my team is using local links.

Example: "overview.rst" links to "detail.rst" like so: see `details <./detail.html>`_

The HTML output is fine, but linkcheck fails because it looks for a file named detail.html, but locally there is only detail.rst.

Is the "right way" to solve this to use document cross-references instead of links?

Thank you!

[westurner]

https://github.com/sphinx-doc/sphinx/blob/master/sphinx/builders/linkcheck.py

.. index: this
.. _that:
.. _this:

This
=====

:ref:`this` - which references ``.. _this:`` -
 works between all docs included in the sphinx build.

:ref:`that` does as well.

:ref:`also <this>`
:ref:`also <that>`

`this`_ works because there's a "this" heading 

`this <this.html>`_
`this <this.rst>`_
`this <this>`_

`this <this.html>`__
`this <this.rst>`__
`this <this>`__

This will log an error about
the duplicate reference if it's in any doc in the build:

.. _this:

[westurner]

Docs for hyperlinking with docutils and Sphinx:

https://www.sphinx-doc.org/en/1.8/usage/restructuredtext/roles.html#ref-role

https://www.sphinx-doc.org/en/1.8/usage/restructuredtext/basics.html#hyperlinks

https://www.sphinx-doc.org/en/1.8/usage/restructuredtext/roles.html#role-doc :

:doc:`this`
:doc:`this one <this>`

^^ that'll work in Sphinx but not in a GH rst render. Could you omit the extension from the link? (There's a conf.py option to remove the .HTML from sphinx-generated links: /a/b.html. -> /a/b)

`anchor text <this>`_

Trying to remember what the trailing double underscore does for hyperlinks?

`anchor text <this>`__

[tk0miya]

Yes, :doc: role is good to make a cross-reference to another document. And I don't recommend to use hyperlink notation (ex. `anchor text <this>`_) for such purpose. Because it would not work on non-HTML builds like PDF.

[tuukkamustonen]

@tk0miya This seems to be problematic with something like:

.. figure:: architecture.png
   :target: ../../_images/architecture.png

Target (../../_images/architecture.png) exists and works correctly in the rendered HTML, but link checker marks it as failure.

Is there a workaround?

[westurner]

Could you raise an exception in linkcheck and drop into ipdb/pdb++?

python -m venv sphinx
source ./sphinx/bin/activate
echo "${VIRTUAL_ENV}"

pip install -e git+https://github.com/sphinx-doc/sphinx#egg=sphinx
pip install pdbpp pytest-cov

# cd "${VIRTUAL_ENV}/src/sphinx"
cd ./sphinx/src/sphinx
# create an Exception (where?) and a test_ function
pytest --pdb

[tuukkamustonen]

@westurner Was that a reply for me? What is the intent of the steps you posted?

[westurner]

That may be the best bet for debugging why the Figure directive with a relative target is failing linkcheck?

Things to test in a test that raises an exception so that you can interactively pdb to debug:

• Do other directives with e.g. relative targets fail?
• Is it necessary to e.g. urlsafe_normpath() if that's not already the case?
• Does the file exist when linkcheck is run

To add a temporary exception In the linkcheck callable in order to write a test that recreates the error conditions and/or just fix the bug:

if x.attr == '../../_images/architecture.png':
    raise Exception()

[tk0miya]

Hmm... it's difficult situation. The target file will be available only on building HTML. Because the files under _images are copied by HTML builder. It means they're not available on linkcheck. It's like a chicken-and-egg problem. I'll try to find the way to avoid the problem. Could you file an issue, please?

[tuukkamustonen]

@tk0miya Opened #9383.

[tuukkamustonen]

@westurner Thank you for the instructions to investigate the issue. Luckily, not needed here but I'll bookmark mentally :)