Skip to content

Turn on Sphinx Link checker on CI? #5380

Open

Description

@jenshnielsen

The linkchecker that we use at the moment does not seem to check external links hence #5379 and others

I tried turning on the sphinx linkchecker python make.py linkcheck which seems to work but generate a fair number of redirect warnings and errors. Perhaps it is worth turning this on pr default?

See https://gist.github.com/jenshnielsen/b3dceef10df743154942 for the present output.

The linkcheck command is broken on python 3.5 but that should be fixed in the next Sphinx point release

Activity

  1. changed the title [-]Turn on Sphinx Link checker on Travis[/-] [+]Turn on Sphinx Link checker on Travis?[/+] on Nov 2, 2015
  2. mdboom commented on Nov 2, 2015

    @mdboom
    Member

    Thanks. I didn't realize we weren't checking external links, so this is great. Also solves the problem that linkchecker doesn't work on Python 3.x.

  3. tacaswell commented on Nov 2, 2015

    @tacaswell
    Member

    Huh, nifty that sphinx has that functionality built in....

  4. added this to the milestone on Nov 2, 2015
  5. modified the milestones: , on May 3, 2017
  6. modified the milestones: , on Oct 9, 2017
  7. timhoffm commented on Apr 13, 2020

    @timhoffm
    Member

    How it works: Essentially, from docs run

    make linkcheck
    

    Open issues:

    • When I ran this, github temporarily blocked me because of suspected abuse due to many page requests. Possible workaround add linkcheck_ignore = [r'https://github.com/.*'] to conf.py.
      Is too much traffic a general concern if we run this with with every CI build?
    • There's a lot of output and the link checks must be filtered out. Either there has to be a way to silence sphinx mostly or one would have to grep the results.
  8. changed the title [-]Turn on Sphinx Link checker on Travis?[/-] [+]Turn on Sphinx Link checker on CI?[/+] on Jun 1, 2022
  9. github-actions commented on Jun 2, 2023

    @github-actions

    This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!

  10. 5 remaining items

  11. github-actions commented on Jun 3, 2024

    @github-actions

    This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!

  12. tacaswell commented on Jun 3, 2024

    @tacaswell
    Member

    The best path here is what @rcomer suggests: have a weekly or monthly job that runs the checks. We should copy the preselease job and have it open an issue on failure.

    Marking as good first issue because there should be no library changes. The steps are

    1. understand how to run the link checker locally
    2. fix any broken links
    3. understand how to run the link checker on GHA
    4. set up low-ferquency cron job that creates an issues on failure
  13. added
    🌱 Good first issueOpen a pull request against these issues if there are no active ones!
    on Jun 3, 2024
  14. github-actions commented on Jun 3, 2024

    @github-actions

    Good first issue - notes for new contributors

    This issue is suited to new contributors because it does not require understanding of the
    Matplotlib internals. To get started, please see our contributing
    guide
    .

    We do not assign issues. Check the Development section in the sidebar for linked pull
    requests (PRs). If there are none, feel free to start working on it. If there is an open PR, please
    collaborate on the work by reviewing it rather than duplicating it in a competing PR.

    If something is unclear, please reach out on any of our communication
    channels
    .

  15. dopplershift commented on Jun 3, 2024

    @dopplershift
    Contributor

    On MetPy we have a script that can be used to filter only to links added in the most recent merge so you can check links in a PR. Then the nightly/unstable build checks all the links.

  16. rcomer commented on Mar 28, 2025

    @rcomer
    Member

    FWIW the other project I mentioned just moved to link checking in a scheduled action, using something called lychee. This is all I know. SciTools/iris#6386

    Edit: and it made its first report SciTools/iris#6390

  17. immortal71 commented on Nov 16, 2025

    @immortal71

    @jenshnielsen Hi! I’d like to help with enabling the Sphinx link checker for the documentation build. Is anyone currently working on this, or can I get started? Any tips or preferred approach?

  18. tacaswell commented on Nov 16, 2025

    @tacaswell
    Member

    I think both of the latest suggestions (identifying new links and checking them in the PR and a scheduled job that opens issues) are worth perusing.

    The biggest issue with any of these checkers is that our docs contain a lot of links which is both time consuming and runs the risk of looking like a malicious actor (both from GHA looking at what is going out and inbound on sites we link to).

  19. immortal71 commented on Nov 17, 2025

    @immortal71

    @tacaswell Thanks for the feedback! I’ll look into both approaches—checking new links in PRs and setting up a scheduled job to report broken links. I’ll also review how Sphinx linkcheck can be integrated into the CI while minimizing unnecessary requests. If I have any questions or need guidance, I’ll reach out here. Appreciate the suggestions!

  20. added a commit that references this issue on Feb 23, 2026
    02f6b92
  21. removed
    🌱 Good first issueOpen a pull request against these issues if there are no active ones!
    on Feb 25, 2026
  22. tacaswell commented on Feb 25, 2026

    @tacaswell
    Member

    I took off good first issue to not draw any more AI spam to this issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions