Dev update install instructions (simonsobs#127)

* updated install instructions and readme

* updated install instructions

* updated install instructions

* updates to readme

* change image path for readme

* added logo

* create separeate text for readme and docs index

* removed old instructions from install.rst

* added developers page to consolidate guidance

* added docs guidelines page

* typos and move docs doc

* remove depracated files

* removed old guidelines, integrated into developers.rst

* changed dev guidleines name in readme

* add sphinxemoji

* remove emoji :-(

* remove env build from readthedocs

* readd env build from readthedocs as necessary

* added missing workflow docs page

* Update README.rst

Co-authored-by: reneehlozek <renee.hlozek@gmail.com>

* Update README.rst

Co-authored-by: reneehlozek <renee.hlozek@gmail.com>

* Update docs/developers.rst

Co-authored-by: reneehlozek <renee.hlozek@gmail.com>

* docs fixes after review

---------

Co-authored-by: Martina Gerbino <bradamante@martina.local>
Co-authored-by: Ian Harrison <itrharrison@gmail.com>
Co-authored-by: reneehlozek <renee.hlozek@gmail.com>

INSTALL.rst

@@ -16,11 +16,11 @@ Optional: Install CosmoPower
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 In order to use the CosmoPower Theories within SOLikeT you will need to additionally install CosmoPower (and with it tensorflow, which is rather heavy and hence left out of the default installation).
 
-This should be easily achievable with::
+Unless using an M1 Mac this should be easily achievable with::
 
   $ pip install cosmopower
 
-If you wish to install it using your own system tools some useful information is provided below.
+If you wish to install it using your own system tools (including new M1 Mac) some useful information is provided below.
 
 Harder Way: Preparing your own conda environment
 ----------------------------------
@@ -59,7 +59,7 @@ Based on `cobaya documentation <https://cobaya.readthedocs.io/en/latest/cluster_
 At NERSC
 --------
 
-Note: you may want to run cobaya in the SCRATCH directory (see thread `here <https://github.com/CobayaSampler/cobaya/issues/219>`_).
+Based on CORI. To be checked against Perlmutter yet. Note: you may want to run cobaya in the SCRATCH directory (see thread `here <https://github.com/CobayaSampler/cobaya/issues/219>`_).
 
 **CREATE A CONDA-ENV COPYING LAZY-MPI4PY AND USING GNU**
 Based on `NERSC documentation <https://docs.nersc.gov/development/languages/python/parallel-python/#mpi4py>`_.
@@ -98,3 +98,47 @@ Based on `NERSC documentation <https://docs.nersc.gov/development/languages/pyth
 Create your job script following `cobaya docs <https://cobaya.readthedocs.io/en/devel/run_job.html>`_.
 
 Many thanks to Luca Pagano, Serena Giardiello, Pablo Lemos, +++
+
+On M1 Mac
+--------
+There is an issue with installing tensorflow (needed for cosmopower) on M1 Mac that is likely to be solved in the future. For the moment, if you want to couple SOLikeT to cosmopower, please follow this guidance:
+
+1. Download latest miniconda installer (e.g., `here: Download Conda environment <https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh>`_) and properly rename it (e.g., -> miniconda.sh)
+2. Install miniconda and tensor flow-deps
+
+::
+
+   bash ~/miniconda.sh -b -p $HOME/miniconda
+   source ~/miniconda/bin/activate
+   conda install -c apple tensorflow-deps
+
+3. git clone soliket and create your virtual env
+
+::
+
+   git clone https://github.com/simonsobs/soliket
+   cd soliket
+   conda env create -n my_env -f soliket-tests.yml
+   conda activate my_env 
+
+4. Install tensorflow-macos and metal with correct versioning
+
+::
+
+   pip install tensorflow-macos
+   pip install tensorflow-metal
+
+5. Download and install cosmopower manually
+
+::
+
+   git clone https://github.com/alessiospuriomancini/cosmopower
+   cd cosmopower
+   pip install .
+
+6. Go back to soliket folder and install it
+
+::
+
+   cd path/to/your/soliket
+   pip install -e .

README.rst

@@ -1,5 +1,5 @@
 =======
-SOLikeT
+SOLikeT: SO Likelihoods and Theories
 =======
 
 .. image:: https://github.com/simonsobs/soliket/workflows/Testing/badge.svg
@@ -14,53 +14,51 @@ SOLikeT
    :target: https://soliket.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status
 
-**SO Likelihoods and Theories**
-
-A centralized package for likelihood and theory implementations for SO.
+SOLikeT is a centralized package for likelihood and theory implementations for the `Simons Observatory <https://simonsobservatory.org/>`_.
+For more extensive details please see our main documentation pages at: `http://soliket.readthedocs.io/ <http://soliket.readthedocs.io/>`_.
 
+.. image:: docs/images/Sky_UCSD2b.jpg
+   :target: https://simonsobservatory.org/
+   :alt: Simons Observatory Logo
+   :width: 200
 
 Installation
 ============
 
-For a set of detailed instructions for different machines (e.g. NERSC), please see `the installation page <INSTALL.rst>`_.
-
-To install SOLikeT we expect that you have the following system-level tools:
-
-* python>=3.7,<3.11
-* pip
-* compilers (c, cxx, fortran)
-* cmake
-* swig
-* gsl
-* fftw
-* cython
-* mpi4py
-
-A convenient way to obtain these things (along with the python dependencies listed in requirements.txt) is through using the conda environment in soliket-tests.yml. This conda environment is the one we use for running tests.
+For a set of detailed requirements and installation instructions for different machines (e.g. NERSC, M1 Mac), please see `the installation page <INSTALL.rst>`_.
 
-You can then install SOLikeT in the usual way with 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
+  conda env create -f soliket-tests.yml
+  conda activate soliket-tests
   pip install -e .
 
 
-Optional Extras
----------------
+Running an Example
+==================
 
-In order to use the CosmoPower Theories within SOLikeT you will need to additionally install CosmoPower (and with it tensorflow, which is rather heavy and hence left out of the default installation).
+SOLikeT is a collection of modules for use within the Cobaya cosmological inference and sampling workflow manager. Please see `the Cobaya documentation <https://cobaya.readthedocs.io/en/latest/>`_ for detailed instructions on how to use Cobaya to perform cosmological calculations and generate constraints on cosmological parameters.
 
-This should be easily achievable with::
+SOLikeT examples and explanatory notebooks are under construction, but will be run using standard [yaml](https://en.wikipedia.org/wiki/YAML) format (which can in turn be read in as Python dictionaries). The examples will be run using something similar to::
 
-  pip install cosmopower
+  cobaya-run soliket-example.yml
 
 
+Developing SOLikeT Theories and Likelihoods
+===========================================
+
+If you wish to develop your own Theory and Likelihood codes for use in SOLikeT please see the detailed instructions on the `Developer Guidelines <docs/developers.rst>`_ page.
+
 Running Tests
 =============
 
-There are (at least) two reasons you might want to run tests:
+Tests run a set of SOLikeT calculations with known expected results. There are (at least) two reasons you might want to run tests:
 
-1. To see if tests you have written when developing SOLikeT are valid and will pass the Continuous Integration (CI) tests which we require for merging on github.
+Checking code in development
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To see if codes you have written when developing SOLikeT are valid and will pass the Continuous Integration (CI) tests which we require for merging on github.
 
 If you are using conda, the easiest way to run tests (and the way we run them) is to use tox-conda::
 
@@ -77,9 +75,12 @@ will only run tests which have names containing the string 'my_new_model', and :
 
 will start a pdb debug instance when (sorry, *if*) a test fails.
 
-2. Check SOLikeT is working as intended in an environment of your own specification.
+Checking environment configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Check SOLikeT is working as intended in a python environment of your own specification (i.e. you have installed SOLikeT not using the solike-tests conda environment).
+
 
-For this you need to make sure all of the above system-level and python dependencies are working correctly, then run::
+For this you need to make sure all of the required system-level and python dependencies described in `the installation instructions <INSTALL.rst>`_ are working correctly, then run::
 
   pytest -v soliket
 

docs/ccl.rst

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