Adds .readthedocs.yaml to fix RTD build

[heyhaleema]

This PR adds a ReadTheDocs (RTD) configuration file (see docs here and closed issue here) since the build is currently failing due to outdated Python version being used in virtual environment (see error message here).

[github-actions[bot]]

Coverage Report

File	Stmts	Miss	Cover	Missing
hazenlib
HazenTask.py	24	3	88%	29–31
__init__.py	147	38	74%	136, 140, 150, 155, 192, 199–204, 215, 218–225, 245–247, 265–267, 286–288, 297, 302, 308, 359, 379–381, 389–390, 394
exceptions.py	21	4	81%	17–21
relaxometry.py	317	90	72%	238–256, 631, 690–692, 746, 794–816, 834–849, 1174–1177, 1186–1189, 1201–1214, 1217–1222, 1233–1263
shapes.py	20	9	55%	13, 16, 24–29, 32
snr_map.py	108	5	95%	403, 408–410, 439
tools.py	84	8	90%	43–50, 92, 101, 117
hazenlib/tasks
ghosting.py	150	51	66%	18–32, 47, 109–110, 114, 124–125, 151–153, 170–172, 218–256
relaxometry.py	7	2	71%	10–11
slice_position.py	118	22	81%	31, 40–41, 103–104, 130, 210, 217–234
slice_width.py	356	52	85%	34–37, 107, 166–186, 451, 456–457, 463, 468, 530–531, 780–821
snr.py	163	66	60%	62–67, 161–179, 194–203, 221–231, 258–268, 273–283, 314–327, 332–340, 369–382
snr_map.py	7	7	0%	1–11
spatial_resolution.py	246	44	82%	36–39, 62, 147, 206, 332–368
task_acr_ghosting.py	116	42	64%	33–53, 91–93, 123–125, 161–194
task_acr_uniformity.py	89	32	64%	34–54, 121–138
uniformity.py	78	19	76%	42–45, 91–92, 99, 133–147
TOTAL	2067	494	76%

Tests	Skipped	Failures	Errors	Time
180	0 :zzz:	0 :x:	0 :fire:	2m 16s :stopwatch:

[hshuaib90]

This branch is still failing to build on RTD

[heyhaleema]

@hshuaib90 It looks like that build checked out main rather than add-rtd-yaml, so I did some testing on fix-readthedocs and it now works again there (see build here). I think the main issue is that if you use the RTD configuration file, the default sphinx version is (assumedly) the latest, i.e. 5.3.0.

We used this configuration file in order to be able to install a later version of scipy with an updated Python version, but sphinx 5.3.0 doesn't seem to support sphinxcontrib-bibtex (see build here). The fix was to include/uncomment the option to install requirements.txt so that we could pin the Sphinx version before the default was used/rest of the build continues.

[hshuaib90]

I'm slightly confused. Why is the build on RTD not referencing this branch but the fix_readthedocs branch instead? How do we know this branch will build when it merges to main?

[heyhaleema]

@hshuaib90 I think it's because we currently* need to explicitly activate the branches/versions we want RTD to trigger a build on:

We would ideally then activate the relevant development branch prior to merging with main (or release branch?) to reconfirm the RTD build hasn't broken, so if you activate add-rtd-yaml, we can see if it works there, too. The latest version hasn't yet passed successfully because of that issue with the newerscipy version which is why it's only passed on fix-readthedocs since that branch was using an older version.

* It looks like we can automate this - see here.

[hshuaib90]

Yes you are right! Sorry, just built it and it works.