Merge pull request #5185 from TimKam/4886-linkcheck-ignore-doc

4886 correct link check ignore doc

doc/usage/configuration.rst

@@ -2488,12 +2488,21 @@ Options for the linkcheck builder
 
 .. confval:: linkcheck_anchors_ignore
 
-   A list of regular expressions that match URIs that should skip checking
-   the validity of anchors in links. This allows skipping entire sites, where
-   anchors are used to control dynamic pages, or just specific anchors within
-   a page, where JavaScript is used to add anchors dynamically, or use the
-   fragment as part of to trigger an internal REST request. Default is
-   ``["/#!"]``.
+   A list of regular expressions that match anchors Sphinx should skip when
+   checking the validity of anchors in links. This allows skipping anchors that
+   a website's JavaScript adds to control dynamic pages or when triggering an
+   internal REST request. Default is ``["^!"]``.
+
+   .. note::
+
+      If you want to ignore anchors of a specific page or of pages that match a
+      specific pattern (but still check occurrences of the same page(s) that
+      don't have anchors), use :confval:`linkcheck_ignore` instead, for example
+      as follows::
+
+         linkcheck_ignore = [
+            'http://www.sphinx-doc.org/en/1.7/intro.html#'
+         ]
 
    .. versionadded:: 1.5
 

tests/roots/test-linkcheck/links.txt

@@ -9,3 +9,5 @@ Some additional anchors to exercise ignore code
 * `Example Bar invalid <http://example.com/#!bar>`_
 * `Example Bar invalid <http://example.com#!bar>`_ tests that default ignore anchor of #! does not need to be prefixed with /
 * `Example Bar invalid <http://example.com/#top>`_
+* `Example anchor invalid <http://www.sphinx-doc.org/en/1.7/intro.html#does-not-exist>`_
+* `Complete nonsense <https://localhost:7777/doesnotexist>`_

tests/test_build_linkcheck.py

@@ -21,14 +21,21 @@ def test_defaults(app, status, warning):
     content = (app.outdir / 'output.txt').text()
 
     print(content)
-    # looking for #top should fail
+    # looking for '#top' and 'does-not-exist' not found should fail
     assert "Anchor 'top' not found" in content
-    assert len(content.splitlines()) == 1
+    assert "Anchor 'does-not-exist' not found" in content
+    # looking for non-existent URL should fail
+    assert " Max retries exceeded with url: /doesnotexist" in content
+    assert len(content.splitlines()) == 3
 
 
 @pytest.mark.sphinx(
     'linkcheck', testroot='linkcheck', freshenv=True,
-    confoverrides={'linkcheck_anchors_ignore': ["^!", "^top$"]})
+    confoverrides={'linkcheck_anchors_ignore': ["^!", "^top$"],
+                   'linkcheck_ignore': [
+                       'https://localhost:7777/doesnotexist',
+                       'http://www.sphinx-doc.org/en/1.7/intro.html#']
+                   })
 def test_anchors_ignored(app, status, warning):
     app.builder.build_all()