Updated readthedocs.yml to linkcheck #4712
Conversation
RohitP2005
requested review from
martinjrobins,
Saransh-cpp,
agriyakhetarpal,
kratman and
arjxn-py
as code owners
|
Previous discussion: #4686 |
|
Thanks, this looks reasonable. As mentioned, you can ignore some of the links that Lychee is ignoring as well, but the rest of the failing links will either have to be removed, replaced, or fixed before we can approve this. |
|
@agriyakhetarpal understood, in the next commit I will add the links to be ignored and then we can work on the failing links |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## develop #4712 +/- ##
===========================================
- Coverage 99.22% 99.22% -0.01%
===========================================
Files 303 303
Lines 23070 23101 +31
===========================================
+ Hits 22891 22921 +30
- Misses 179 180 +1 ☔ View full report in Codecov by Sentry. |
|
I ran the build locally and have logs of the broken links. I’ve added the ScienceDirect links to be ignored. For the other broken links, we can ignore the warnings temporarily to let the build complete and address them later. Let me know if you'd prefer to prioritize fixing them now. |
There was a problem hiding this comment.
Yes, my preference is that we fix all of the broken links, since based on the previous RTD build, there are not many (around 13): https://readthedocs.org/projects/pybamm/builds/26675630/
You may refer to https://www.sphinx-doc.org/en/master/usage/referencing.html#role-ref which describes the proper way to reference headings in Sphinx. That is, you need to add labels for the headings that are being reported as broken that can be used as a reference (and reference the labels if they already exist).
For example, for the broken link for the IREE solver (line 42 in installation/index.rst), we already have a reference in line 108 of installation/gnu-linux-mac.rst as follows:
.. _optional-iree-mlir-support:Hence, this change should fix it:
- * `IREE <https://iree.dev/>`_ (`MLIR <https://mlir.llvm.org/>`_) support, see `Optional - IREE / MLIR Support <gnu-linux-mac.html#optional-iree-mlir-support>`_.
+ * `IREE <https://iree.dev/>`_ (`MLIR <https://mlir.llvm.org/>`_) support, see :ref:`optional-iree-mlir-support`.and similarly for the other internal broken links. For external broken links, if there is an easy replacement, we should do that, otherwise we should add them to the ignore list too..
Refernce for broken linksInternal Broken Links
External Broken Links
|
|
The build ran successfully locally , but failed @agriyakhetarpal |
|
Yes, there are some error messages (please see the Read the Docs job) such as this:
which now need to be fixed. You may refer to https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections to see how Sphinx processes different levels of headings, which might be helpful. Also, I'm not sure Thanks for staying put on this, it's almost there! |
|
@agriyakhetarpal I will look into it. |
Sphinx Build Error: Title Level Inconsistency in
|
|
The build is still failing , i will refactor the headings and make another commit |
|
@agriyakhetarpal can u help me, why the build is still failing? |
|
The timeout fixed it i suppose |
|
The dropdown menus on the docs seem to have been broken: Before: Now: |
Co-authored-by: Agriya Khetarpal <[email protected]>
Co-authored-by: Agriya Khetarpal <[email protected]>
|
@agriyakhetarpal I just have the one last RTD link thing so we can skip the suppression |
|
@all-contributors please add @RohitP2005 for docs and infra |
|
I've put up a pull request to add @RohitP2005! 🎉 |
|
@RohitP2005 We just need you to change https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md#a-before-you-begin to https://docs.pybamm.org/en/latest/source/user_guide/contributing.html#a-before-you-begin and remove the link suppression. Then we can get this merged |
got it Eric, will commit in a min |
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
|
Just waiting for tests to pass |
Anytime Erick , Happy to contribute. |
|
@agriyakhetarpal Now that this issue is sorted , ig i will work on the other ones aswell |
Description
This PR introduces a new pre-build step to the
readthedocs.ymlconfiguration for PyBaMM. The change adds alinkcheckoperation to ensure that all links in the documentation are checked for validity during the build process on Read the Docs.Changes made:
pre_buildstep to thereadthedocs.ymlfile.pre_buildstep runs thesphinx -b linkcheckcommand, which checks all links in the documentation before the build proceeds.linkcheck_timeout=1) to handle any slow links more efficiently.This ensures that if any broken links exist in the documentation, they are caught early during the build process.
Fixes #3387
Type of change
Please add a line in the relevant section of CHANGELOG.md to document the change (include PR #) - note reverse order of PR #s. If necessary, also add to the list of breaking changes.
Key checklist:
$ pre-commit run(or$ nox -s pre-commit) (see CONTRIBUTING.md for how to set this up to run automatically when committing locally, in just two lines of code)$ python -m pytest(or$ nox -s tests)$ python -m pytest --doctest-plus src(or$ nox -s doctests)You can run integration tests, unit tests, and doctests together at once, using
$ nox -s quick.Further checks: