pip install instructions (#65)

* pip install instructions
* correct paths

Signed-off-by: Nathaniel Starkman <[email protected]>

README.rst

@@ -1,4 +1,36 @@
 Cosmology API
 =============
 
-API standard for Cosmology libraries.
+There are a lot of (Python) cosmology libraries out there, from big projects --
+including `Astropy <https://docs.astropy.org/en/stable/cosmology/index.html>`_,
+`CLASS <http://class-code.net>`_, and `CAMB
+<https://camb.readthedocs.io/en/latest/>`_ -- down to small personal scripts.
+These libraries perform many of the same tasks, but they all have different
+interfaces, and different ways of doing things. This makes it hard to switch
+between libraries, and nearly impossible to write code that works with multiple
+libraries.
+
+The Cosmology API for Python solves this problem, providing detailed interfaces
+for cosmology codes, from individual methods and functions up to fully-featured
+cosmology objects, even whole libraries. Best of all, using the Cosmology API
+does not require any run-time dependencies, even this library!
+
+With the Cosmology API you can **write code that works with anything that
+implements the API**, i.e many different cosmology libraries. We provide the
+easy-to-use, well-defined descriptions, you can build functions that work with
+any supporting library. For example
+
+.. skip: next
+.. code-block:: python
+
+   # No implementation, just a description of the interface!
+   from cosmology.api import StandardCosmology
+
+
+   def flat_angular_diameter_distance(
+       cosmo: StandardCosmology[Array, Array], z: Array
+   ) -> Array:
+       # Do some cosmology with any object that implements the API
+       if cosmo.Omega_k != 0:
+           raise ValueError("This function only works for flat cosmologies")
+       return cosmo.comoving_distance(z) / (1 + z)

docs/index.rst

@@ -32,7 +32,7 @@ any supporting library. For example
        cosmo: StandardCosmology[Array, Array], z: Array
    ) -> Array:
        # Do some cosmology with any object that implements the API
-       if cosmo.Omega_k != 0:
+       if cosmo.Omega_k0 != 0:
            raise ValueError("This function only works for flat cosmologies")
        return cosmo.comoving_distance(z) / (1 + z)
 

docs/install.rst

@@ -4,6 +4,23 @@
 Installation
 ************
 
+With ``pip`` (recommended)
+==========================
+
+To install the latest stable version using ``pip``, use
+
+.. code-block:: bash
+
+    python -m pip install cosmology.api
+
+
+To install the latest development version, use:
+
+.. code-block:: bash
+
+    python -m pip install git+https://github.com/cosmology-api/cosmology.api
+
+
 
 From Source: Cloning, Building, Installing
 ==========================================
@@ -13,10 +30,10 @@ The latest development version of cosmology-api can be cloned from `GitHub
 
 .. code-block:: bash
 
-    git clone https://github.com/cosmology-api/cosmology-api.git
+    git clone https://github.com/cosmology-api/cosmology.api.git
 
 To build and install the project (from the root of the source tree, e.g., inside
-the cloned ``cosmology-api`` directory)
+the cloned :mod:`cosmology.api` directory)
 
 .. code-block:: bash
 
@@ -31,5 +48,5 @@ This package has the following dependencies:
 * `Python`_ >= 3.9
 
 Explicit version requirements are specified in the project `pyproject.toml
-<https://github.com/cosmology-api/cosmology-api/blob/main/pyproject.toml>`_.
+<https://github.com/cosmology-api/cosmology.api/blob/main/pyproject.toml>`_.
 ``pip`` and ``conda`` should install and enforce these versions automatically.

pyproject.toml

@@ -46,9 +46,9 @@
   ]
 
 [project.urls]
-  homepage = "https://cosmology.readthedocs.org/api"
-  repository = "https://github.com/cosmology-api/cosmology-api"
-  documentation = "https://cosmology.readthedocs.org/api"
+  homepage = "https://cosmology.readthedocs.org"
+  repository = "https://github.com/cosmology-api/cosmology.api"
+  documentation = "https://cosmology.readthedocs.org"
 
 
 [build-system]