docs fixes after review

README.rst

@@ -27,7 +27,7 @@ Installation
 
 For a set of detailed requirements and installation instructions for different machines (e.g. NERSC, M1 Mac), please see `the installation page <INSTALL.rst>`_.
 
-A preferred and convenient way to install SOLikeT and its dependents is through using the conda environment defined in `soliket-tests.yml <https://github.com/simonsobs/soliket/soliket-tests.yml>`_. After installing an anaconda distribution (e.g. as described `here <https://docs.anaconda.com/free/anaconda/install/index.html>`_), you can create the environment and install a locally cloned version of SOLikeT using pip::
+A preferred and convenient way to install SOLikeT and its dependents is through using the conda environment defined in `soliket-tests.yml <soliket-tests.yml>`_. After installing an anaconda distribution (e.g. as described `here <https://docs.anaconda.com/free/anaconda/install/index.html>`_), you can create the environment and install a locally cloned version of SOLikeT using pip::
 
   git clone https://github.com/simonsobs/soliket
   cd soliket

docs/ccl.rst

@@ -1,5 +1,5 @@
-CCL Calculator
-==============
+The Core Cosmology Library (CCL) Calculator
+===========================================
 
 .. automodule:: soliket.ccl
 

docs/developers.rst

@@ -1,6 +1,6 @@
-==========================
-Information for Developers
-==========================
+==============================
+General Development Guidelines
+==============================
 
 This page describes dow to develop new code within SOLikeT, including changing existing components and adding new ones.
 
@@ -91,17 +91,19 @@ It might be possible that, in order to compute ``cmbfg_dict``, we should pass to
    {"cmbfg_dict": {"param1": param1_value, "param2": param2_value, etc}}
 
 If this happens, then the external Theory block (in this example, ``TheoryForge``) must have a ``must_provide`` function. ``must_provide`` tells the code:
-  1. what values should be assigned to the parameters needed to compute the element required from the Theory block. The required elements are stored in the ``**requirements`` dictionary which is the input of ``must_provide``.
+
+   1. The values which should be assigned to the parameters needed to compute the element required from the Theory block. The required elements are stored in the 
+   ``**requirements`` dictionary which is the input of ``must_provide``.
    In our example, ``TheoryForge`` will assign to ``param1`` the ``param1_value`` passed from ``mflike`` via the ``get_requirement`` in ``mflike`` (and so on). For example:
    ::
 
-      must_provide(self, **requirements):
-         if "cmbfg_dict" in requirements:
-            self.param1 = requirements["cmbfg_dict"]["param1"]
+        must_provide(self, **requirements):
+           if "cmbfg_dict" in requirements:
+              self.param1 = requirements["cmbfg_dict"]["param1"]
 
    if this is the only job of ``must_provide``, then the function will not return anything
 
-   2. if needed, what external elements are needed by this specific theory block to perform its duties. In this case, the function will return a dictionary of dictionaries which are the requirements of the specific theory block. These dictionaries do not have to necessarily contain content (they can be empty instances of the dictionary), but must be included if expected. Note this can be also done via ``get_requirement``. However, if you need to pass some params read from the block above to the new requirements, this can only be done with ``must_provide``. For example, ``TheoryForge`` needs ``Foreground`` to compute the fg spectra, which we store in a dict called ``fg_dict``. We also want ``TheoryForge`` to pass to ``Foreground`` ``self.param1``. This is done as follows:
+   2. If required, what external elements are needed by this specific theory block to perform its duties. In this case, the function will return a dictionary of dictionaries which are the requirements of the specific theory block. These dictionaries do not have to necessarily contain content (they can be empty instances of the dictionary), but must be included if expected. Note this can be also done via ``get_requirement``. However, if you need to pass some params read from the block above to the new requirements, this can only be done with ``must_provide``. For example, ``TheoryForge`` needs ``Foreground`` to compute the fg spectra, which we store in a dict called ``fg_dict``. We also want ``TheoryForge`` to pass to ``Foreground`` ``self.param1``. This is done as follows:
    ::
 
       must_provide(self, **requirements):
@@ -203,8 +205,6 @@ For this you need to make sure all of the required system-level and python depen
 
 Good luck!
 
-If your unit tests check the statistical distribution of a random sample, the test outcome itself is a random variable, and the test will fail from time to time. Please mark such tests with the ``@pytest.mark.flaky`` decorator, so that they will be automatically tried again on failure. To prevent non-random test failures from being run multiple times, please isolate random statistical tests and deterministic tests in their own test cases.
-
 Documentation
 =============
 

docs/documentation.rst

@@ -130,15 +130,14 @@ excessive documentation that the end-user might not really need or should not
 care about. In our Pulsars example, we had the ``extra_function`` that we did
 not want to add to our docs page. For this, there exists the
 ``:exclude-members:`` directive, that will skip given functions that people
-might not need.
+might not need. Care should be taken to ensure this list stays correct and useful
+code does not disappear from the documentation unnecessarily.
 
 
-Obviously, there are many many more ways in which you can make your documentation
-better than whatever example we can come up with. We highly recommend you to
-explore the docstrings written by other people, both inside and outside the
-SOLikeT codes, to improve on your skills to get other people to understand
-your code. The better your documentation, the more likely that other people
-will use your codes for better science.
+We highly recommend you to explore the docstrings written by other people, both 
+inside and outside the SOLikeT codes, to improve on your skills to get other 
+people to understand your code. The better your documentation, the more likely 
+that other people will use your codes for better science.
 
 
 Adding your documentation to the index

docs/index.rst

@@ -8,9 +8,9 @@
    :alt: Simons Observatory Logo
    :width: 200
 
-=======
+====================================
 SOLikeT: SO Likelihoods and Theories
-=======
+====================================
 
 |Read the Docs| |Github| |Codecov|
 
@@ -25,12 +25,10 @@ The pages here describe how to install and run SOLikeT, and document the functio
    :maxdepth: 1
 
    install
-   examples
-   help
 
 .. toctree::
    :caption: Theory codes
-   :maxdepth: 2
+   :maxdepth: 1
 
    bias
    ccl
@@ -40,15 +38,17 @@ The pages here describe how to install and run SOLikeT, and document the functio
 
 .. toctree::
    :caption: Likelihood codes
-   :maxdepth: 2
+   :maxdepth: 1
 
    mflike
 
 .. toctree::
    :caption: Development guidelines
-   :maxdepth: 2
+   :maxdepth: 1
 
    developers
+   workflow
+   documentation
 
 * :ref:`genindex`
 * :ref:`search`

docs/workflow.rst

@@ -6,7 +6,13 @@ If you are a membed of the `Simons Observatory GitHub organisation <https://gith
 
 If you are not a member of the Simons Observatory Collaboration with access to the GitHub org, you can still make contributions via forking this repo, with additional instructions below.
 
-If you are planning on bringing a new Likelihood in to SOLikeT, please have a look at the `guidelines <https://github.com/simonsobs/SOLikeT/blob/master/guidelines.md>`_ which explain how this should be done.
+If you are planning on bringing a new Likelihood or Theory in to SOLikeT, great! 
+It is not required but we would be very happy to hear from you at any stage of 
+development; it is our job to help your contributions go smoothly! An easy way to 
+do this would be to `open an Issue <https://github.com/simonsobs/SOLikeT/issues>`_ 
+describing the modules you would like to add.
+Please have a look at the `guidelines <https://github.com/simonsobs/SOLikeT/blob/master/guidelines.md>`_ for some more detailed guidance on adding new Likelihoods 
+and Theories.
 
 Clone the SOLikeT Repository
 ============================

soliket/ccl.py

@@ -8,10 +8,15 @@
 
    <br />
 
-Simple CCL wrapper with function to return CCL cosmo object, and (optional) result of
-calling various custom methods on the ccl object. The idea is this is included with the
-CCL package, so it can easily be used as a Cobaya component whenever CCL is installed,
-here for now.
+The `Core Cosmology Library (CCL) <https://ccl.readthedocs.io/en/latest/>`_ is a 
+standardized library of routines to calculate basic observables used in cosmology. 
+It will be the standard analysis package used by the LSST 
+Dark Energy Science Collaboration (DESC).
+
+This Theory is a simple CCL wrapper with function to return CCL cosmo object, and 
+(optional) result of calling various custom methods on the ccl object. 
+The idea is this is included with the CCL package, so it can easily be used as a Cobaya 
+component whenever CCL is installed, here for now.
 
 First version by AL. Untested example of usage at
 https://github.com/cmbant/SZCl_like/blob/methods/szcl_like/szcl_like.py