Docs v3

[nikfilippas]

I have started the overhaul of the docstrings:

1. Provide (much) more info about what every piece of code does, with mathematical formulas, definitions, implementation details etc.
2. Uniform style guide following Numpy.

We generally need more docstrings and less code. Below is a list of the so far completed docstrings.

Halos

• [x] halo concentrations
• [x] halo biases
• [x] halo mass functions
• [x] halo model calculator
• [x] halo model pk Npt
• [x] halo mass definitions
• [x] halo profiles
• [x] halo profile 2-pt correlators
• [x] halo model base classes

Main

• [x] baryons & bcm
• [x] base & parameters
• [x] background
• [x] boltzmann
• [x] cells
• [x] cosmology
• [x] correlations
• [x] covariances
• [x] errors
• [x] ~halomodel, haloprofile, massfunction~
• [x] neutrinos
• [x] pk2d
• [x] power
• [x] pyutils
• [x] tk3d
• [x] tracers

nl_pt

• [ ] ?

Write a developer guide [draft]

• [x] Write equations where possible in the docstring. Provide examples with "Examples" section. (#871 )
• [x] Better dev guide. Explain how the modules work together. (#710 ) Things to include: (1) Separate POK/KWO. (2) Expose to public API with __all__. (3) Adheres to the style guide. (4) Write in changelog, contributors etc. (5) Docs/Errors/Warnings: Concise language & messages, (dev guide to provide good/bad examples). No filler words. (6) Don't populate namespace needlessly; see if new feature can be integrated into existing API. No boilerplate code; too much repetition prob means consolidate to single func. (7) Don't import if func is a method of Cosmology. (8) "Returns" & "Raises" section for functions and classes where applicable. (9) Declare useful new attributes in new classes. (10) Prefer inheritance over flags. (11) Prefer type-hinting funcs than docs (except complicated ndarray broadcasting - use scipy conventions there). (12) How to avoid circular imports. (13) Code cov check. (14) No new warnings in unit testing. (15) Import system: builtins/3rd libs/local in AB order. (16) Think of public func names (i.e. is get_blah really a getter? is there a Python builtin instead e.g. __call__). Funcs generally act on something so name should start with a verb. (17) Specify ndarray type covers numbers. (18) Providing references/bibliography. (19) Cross-referencing. (20) Raw (r-) strings for equations. (21) Provide units. (22) Single vs double backticks. (23) Subclasses with just __init__ should probs be funcs. (24) Avoid dict input for extra func parameters. (25) Maintain consistent arg name & order with rest of library. (26) No extra var declarations before return; use direct expression. (27) Try to deal with errors first and have clean, flowing code later instead of if-elif-elif-...-else chains. (28) Same with if-else-return blocks. (29) Funcs/classes. 1-line quick description first, then the rest. (30) New modules: quick description at the top. (31) Properties right after __init__. (32) Docs deprecated/versionadded.
• [ ] Issues/PR templates with checklist to assist both. (#981 ) Box "I have read the dev guide".
• [x] RTD build in CI + check new docs look fine during PR review (use other CCL docs as example).