You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
The text was updated successfully, but these errors were encountered:
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 identifyinglinkcheck
pseudo-failures and maintaining lengthylinkcheck_ignore
andlinkcheck_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 checkinglinkcheck
warnings is a major time commitment if an issue arises.The text was updated successfully, but these errors were encountered: