Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make Sphinx linkcheck return warnings instead of errors #286

Closed
michaelcdevin opened this issue Oct 26, 2023 · 0 comments · Fixed by #287
Closed

Make Sphinx linkcheck return warnings instead of errors #286

michaelcdevin opened this issue Oct 26, 2023 · 0 comments · Fixed by #287
Assignees
Labels
CI Continuous integration (and development)

Comments

@michaelcdevin
Copy link
Collaborator

WecOptTool currently runs the Sphinx linkcheck builder as part of the push and release CI workflows.

Ideally, this should automatically test out all the external links in our docstrings and markdown to confirm that there are no broken links. However, due to websites improving webscrapping detection (see #230, #231, and #241) and issues contacting sites using legacy SSL renegotiation protocols (see #204 (comment)), this causes linkcheck to return fatal errors (thus causing CI runs to fail) despite the identified "bad" links being perfectly fine.

This has resulted in having to maintain a lengthy linkcheck_ignore list and needing spoofed request headers for a number of sites. Not only have these band-aid fixes become more trouble than they are worth, they have resulted in us missing actually broken documentation links!.

For these reasons, I propose reducing the impact of linkcheck in the CI workflow by only returning warnings instead of errors. This way, we can still analyze the Build documentation job in GitHub Actions to see if any external links may be of issue without having to dedicate substantial troubleshooting time to identifying linkcheck pseudo-failures and maintaining lengthy linkcheck_ignore and linkcheck_request_headers lists. While this nominally removes a degree of automation, I don't foresee WecOptTool getting to a point in the near future where manually checking linkcheck warnings is a major time commitment if an issue arises.

@michaelcdevin michaelcdevin added the CI Continuous integration (and development) label Oct 26, 2023
@michaelcdevin michaelcdevin self-assigned this Oct 26, 2023
@michaelcdevin michaelcdevin mentioned this issue Oct 26, 2023
11 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CI Continuous integration (and development)
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant