Review all doc pages before tagging v3

[damonge]

We need to review all of the doc pages on readthedocs, since some of them are a bit antiquated, and some of the autodoc pages show small typos/inaccuracies. This is the last thing to do before we're able to tag v3!

A few instructions for reviewers:

• Virtually no code has changed. I've marked below in comments the only places where this has happened, which had to do with things that had been deprecated long ago but which I only noticed while going through the documentation. Besides this, I don't think it's worth looking at the code itself.
• The most efficient way to review this PR would be to have a systematic look at the documentation pages. I've activated them for this branch here: https://ccl.readthedocs.io/en/doc_review/. I would thus suggest reviewers to look at the doc pages and flag issues as comments here, rather than looking at the code itself.

Of course, reviewers should feel free to proceed as they prefer!

Closes #1091 Closes #867 Closes #871

[coveralls]

Pull Request Test Coverage Report for Build 5789866361

• 6 of 6 (100.0%) changed or added relevant lines in 5 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 97.448%

---

Totals
Change from base Build 5744252840:	0.0%
Covered Lines:	5805
Relevant Lines:	5957

---

💛 - Coveralls

[hsinfan1996]

Update this line? https://github.com/LSSTDESC/CCL/blob/11375ea2a2329c9c7332fa2aacdb192a5dbfa09d/readthedocs/conf.py#L97

[hsinfan1996]

The link is outdated. Should be https://www.numpy.org/ https://github.com/LSSTDESC/CCL/blob/11375ea2a2329c9c7332fa2aacdb192a5dbfa09d/readthedocs/conf.py#L229

[hsinfan1996]

A more detailed table of contents for API Documentation would be great, e.g.

[hsinfan1996]

Is there a reason to use this specific version of sphinx_rtd_theme? https://github.com/LSSTDESC/CCL/blob/b4fbaa74d76f04e7ea63071dcb008c7eb68ed163/readthedocs/requirements.txt#L6

[damonge]

@hsinfan1996 a few months ago the default rtd theme had a few bugs that affected how some things were displayed. We could check if this is now fixed.

Regarding the TOC: do you have a conf.py showing how to do this somewhere?

[hsinfan1996]

@hsinfan1996 a few months ago the default rtd theme had a few bugs that affected how some things were displayed. We could check if this is now fixed.

Regarding the TOC: do you have a conf.py showing how to do this somewhere?

conf.py from CLMM https://github.com/LSSTDESC/CLMM/blob/c6cf806cd9b542f7286187ed0ecb6432f959a767/docs/conf.py#L216-L229

[hsinfan1996]

@hsinfan1996 a few months ago the default rtd theme had a few bugs that affected how some things were displayed. We could check if this is now fixed. Regarding the TOC: do you have a conf.py showing how to do this somewhere?

conf.py from CLMM https://github.com/LSSTDESC/CLMM/blob/c6cf806cd9b542f7286187ed0ecb6432f959a767/docs/conf.py#L216-L229

@damonge Turns out it is just a html_theme_options to be added in the conf.py. No need to modify any .rst files.

[anicola]

I have started going through the top-level docs and just found these super small things. I will now start going through the function docs.

[hsinfan1996]

I removed modules.rst so the TOC looks like

instead of

I can revert it if anyone wants pyccl package to be at the first level.

[damonge]

This looks good. Thanks @hsinfan1996 !

[damonge]

Thanks a lot @anicola , super useful! Just fixed those.

[damonge]

This has been reviewed now by several people, so I'm just using my super powers to merge.