Generate documentation from docstrings

[sophie22]

• following on from 397 standardise docstrings #398 add more docstrings to previously overlooked scripts and functions
• improve docstring formatting for better rendering on ReadTheDocs
• add instructions to generating/updating documentation
• move the relaxometry_params script into the data folder - this is to be excluded from documentation generation, so is the relaxometry task script itself

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
hazenlib
ACRObject.py	107	11	90%	94, 97–99, 104–107, 139, 193–196
HazenTask.py	29	3	90%	67–71
__init__.py	57	15	74%	102, 135–144, 146–155, 157–159, 176–180, 184
exceptions.py	21	5	76%	19–23, 42
utils.py	189	43	77%	76, 80, 101, 114, 147, 162–175, 194, 201–208, 225–227, 242–246, 262–266, 286, 291, 302, 359, 362, 370–375, 378, 433, 442, 471
hazenlib/tasks
acr_geometric_accuracy.py	112	58	48%	53–100, 124–239
acr_ghosting.py	107	42	61%	42–58, 102–105, 152–155, 203–285
acr_slice_position.py	136	48	65%	56–80, 282–349
acr_slice_thickness.py	135	60	56%	44–63, 236–320
acr_snr.py	134	58	57%	45, 60–111, 131, 227–242, 286–304, 354–379
acr_spatial_resolution.py	207	68	67%	69–100, 188, 286, 303–314, 460–539
acr_uniformity.py	80	32	60%	43–60, 145–197
ghosting.py	149	51	66%	28–47, 67, 171–172, 179, 196–197, 252–256, 271–275, 346–387
relaxometry.py	291	89	69%	210–211, 213, 226–231, 238–246, 277–326, 375, 409–431, 609, 655–659, 726, 811–833, 851–866
slice_position.py	124	40	68%	30, 43–71, 129–130, 157, 273, 283–306
slice_width.py	352	52	85%	44–48, 52, 123, 188–213, 555, 560–561, 567, 572, 648–649, 1020–1084
snr.py	173	69	60%	45–48, 87, 103–113, 206–225, 237–247, 287–302, 330–340, 345–361, 399–415, 428–434, 477–495
snr_map.py	108	1	99%	157
spatial_resolution.py	246	44	82%	50–54, 58, 90, 213, 294, 460–503
uniformity.py	80	19	76%	59–63, 67, 118–119, 126, 175–205
TOTAL	2862	808	72%

Tests	Skipped	Failures	Errors	Time
198	0 💤	0 ❌	0 🔥	2m 17s ⏱️

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
hazenlib
ACRObject.py	107	11	90%	94, 97–99, 104–107, 139, 192–195
HazenTask.py	28	3	89%	67–71
__init__.py	56	15	73%	102, 135–144, 146–155, 157–159, 176–180, 184
exceptions.py	21	5	76%	19–23, 42
utils.py	189	43	77%	76, 80, 101, 114, 147, 162–175, 194, 201–208, 226–228, 245–249, 267–271, 291, 296, 307, 364, 367, 375–380, 383, 438, 447, 476
hazenlib/tasks
acr_geometric_accuracy.py	119	62	48%	54–101, 119–165, 186–255
acr_ghosting.py	107	42	61%	46–62, 105–107, 159–161, 211–293
acr_slice_position.py	136	48	65%	59–83, 286–353
acr_slice_thickness.py	136	60	56%	48–67, 238–322
acr_snr.py	134	58	57%	47, 62–113, 132, 227–242, 283–301, 348–373
acr_spatial_resolution.py	207	68	67%	69–100, 188, 286, 303–314, 460–539
acr_uniformity.py	81	32	60%	47–64, 148–200
ghosting.py	150	52	65%	28–47, 67, 171–172, 179, 196–197, 252–256, 271–275, 346–387
relaxometry.py	290	89	69%	210–211, 213, 226–231, 238–246, 277–326, 375, 409–431, 609, 655–659, 726, 811–833, 851–866
slice_position.py	124	40	68%	30, 43–71, 129–130, 157, 273, 283–306
slice_width.py	351	53	85%	44–48, 52, 123, 188–213, 383, 555, 560–561, 567, 572, 648–649, 1020–1084
snr.py	173	69	60%	45–48, 87, 103–113, 206–225, 237–247, 287–302, 330–340, 345–361, 399–415, 428–434, 477–495
snr_map.py	107	1	99%	157
spatial_resolution.py	246	45	82%	50–54, 58, 90, 191, 213, 294, 460–503
uniformity.py	80	19	76%	59–63, 67, 118–119, 126, 175–205
TOTAL	2867	815	72%

Tests	Skipped	Failures	Errors	Time
198	0 💤	0 ❌	0 🔥	2m 15s ⏱️

[sophie22]

ReadTheDocs is able to build documentation!!!

[sophie22]

https://readthedocs.org/projects/hazen/builds/23408263/
https://hazen.readthedocs.io/en/397-standardise-docstrings/hazenlib.tasks.acr.html

[sophie22]

Latest documentation built on ReadTheDocs: https://hazen.readthedocs.io/en/397-standardise-docstrings/

[tomaroberts]

Thanks @sophie22 – just a couple of minor comments and changes to comments.