Updated readthedocs.yml to linkcheck

[RohitP2005]

Description

This PR introduces a new pre-build step to the readthedocs.yml configuration for PyBaMM. The change adds a linkcheck operation to ensure that all links in the documentation are checked for validity during the build process on Read the Docs.

Changes made:

• Added a pre_build step to the readthedocs.yml file.
• The pre_build step runs the sphinx -b linkcheck command, which checks all links in the documentation before the build proceeds.
• The command is configured to have a short timeout (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.

• New feature (non-breaking change which adds functionality)
• Optimization (back-end change that speeds up the code)
• Bug fix (non-breaking change which fixes an issue)

Key checklist:

• No style issues: $ 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)
• All tests pass: $ python -m pytest (or $ nox -s tests)
• The documentation builds: $ 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:

• Code is commented, particularly in hard-to-understand areas
• Tests added that prove fix is effective or that feature works

[kratman]

Previous discussion: #4686

[agriyakhetarpal]

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.

[RohitP2005]

@agriyakhetarpal understood, in the next commit I will add the links to be ignored and then we can work on the failing links

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.22%. Comparing base (a7253b8) to head (5f2246a).
Report is 8 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #4712   +/-   ##
========================================
  Coverage    99.22%   99.22%           
========================================
  Files          303      303           
  Lines        23070    23077    +7     
========================================
+ Hits         22891    22898    +7     
  Misses         179      179           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[RohitP2005]

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.

[agriyakhetarpal]

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..

[agriyakhetarpal]

Could you please explain what this is for? It looks like it breaks the build:
https://readthedocs.org/projects/pybamm/builds/26675902/

[RohitP2005]

This variable is intended to define the output directory for build artifacts like link checks or PDFs.

[RohitP2005]

Refernce for broken links

Internal Broken Links

1. gnu-linux-mac.html#optional-iree-mlir-support in source/user_guide/installation/index.rst at line 42
2. gnu-linux-mac.html#optional-jaxsolver in source/user_guide/installation/index.rst at line 41
3. index.html#dependencies in source/user_guide/installation/index.rst at line 19
4. index.html#install-required-dependencies in source/user_guide/installation/gnu-linux-mac.rst at line 87
5. index.html#installation in source/user_guide/installation/gnu-linux-mac.rst at line 106
6. install-from-source.html in source/user_guide/installation/windows-wsl.rst at line 40
7. source/user_guide/contributing.html in index.rst at line 110
8. source/user_guide/installation/index.html in index.rst at line 23
9. windows-wsl.html in source/user_guide/installation/windows.rst at line 110

External Broken Links

1. Google Books - Finite Volume Methods for Hyperbolic Problems in source/examples/notebooks/spatial_methods/finite-volumes.ipynb at line 22
2. DOI - 10.1137/20M1336898 in source/api/models/submodels/current_collector/effective_resistance_current_collector.rst at line 10 (403 Forbidden)
3. [Wikipedia - Rectifier (neural networks)](https://en.wikipedia.org/wiki/Rectifier_(neural_networks) in source/examples/notebooks/solvers/speed-up-solver.ipynb at line 1215 (404 Not Found)
4. GitHub - Contributing Guide in source/examples/notebooks/spatial_methods/finite-volumes.ipynb at line 1914 (Anchor not found)

[RohitP2005]

The build ran successfully locally , but failed @agriyakhetarpal

[agriyakhetarpal]

Yes, there are some error messages (please see the Read the Docs job) such as this:

/home/docs/checkouts/readthedocs.org/user_builds/pybamm/checkouts/4712/docs/source/user_guide/installation/index.rst:153: CRITICAL: Title level inconsistent:

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 linkcheck_timeout=1 might be too less to be able to check GitHub URLs.

Thanks for staying put on this, it's almost there!

[RohitP2005]

@agriyakhetarpal I will look into it.
I am also looking forward to complete this task.