updated docs

- improved install docs (README)
- added tips section
- improved environment lists

fixes #5

.gitlab-ci.yml

@@ -76,6 +76,8 @@ docs:
   script:
     - cd docs
     - python3 -m sphinx -M html . ../build/sphinx -vv
+    # remove index.html in links because duncan is _really_ pedantic
+    - find ../build/sphinx/html -name "*.html" -type f -exec sed -i "s/index.html//g" {} +
   artifacts:
     paths:
       - build/sphinx/html

README.rst

@@ -17,19 +17,42 @@ using the `conda <https://conda.io>`_ package manager, and the
 Quickstart
 ==========
 
-1. Install conda (or `Miniconda <https://conda.io/miniconda/>`_)
+**Use a pre-built environment (linux only):**
+
+1. Install and configure CVMFS (instructions coming soon!)
+
+2. Configure ``conda``:
+
+   .. code-block:: bash
+
+       source /cvmfs/ligo-containers.opensciencegrid.org/lscsoft/conda/latest/etc/profile.d/conda.sh
+
+3. Activate an environment:
+
+   .. code-block:: bash
+
+       conda activate ligo-py37
+
+For more details see `Reference environments <https://docs.ligo.org/lscsoft/conda/environments/>`_.
+
+**Or install miniconda yourself:**
+
+1. `Install Miniconda <https://conda.io/projects/conda/en/latest/user-guide/install/index.html>`_.
 
 2. Add the conda-forge channel:
 
-   ::
+   .. code-block:: bash
 
       conda config --add channels conda-forge
 
-3. Install packages:
+3. Create an environment full of packages:
+
+   .. code-block:: bash
 
-   ::
+      conda create --name myenv python=3.7 gwpy python-lal ...
 
-      conda install gwpy pycbc ...
+For either solution, see `Tips and tricks <https://docs.ligo.org/lscsoft/conda/tips/>`_ for
+more useful hints.
 
 Contributing
 ============

docs/environments/index.rst

+.. _lscsoft-conda-reference-environments:
+
 ======================
 Reference environments
 ======================
 
 The LSCSoft Conda team currently defines reference environments for a number
-of version of Python.
+of versions of Python.
 You can install these by downloading the relevant YAML file from the repository
 and installing them.
 
+
+.. _lscsoft-conda-pre-built-environments:
+
 ----------------------
 Pre-built environments
 ----------------------
@@ -35,6 +40,9 @@ You can then activate one of these environments:
 
    conda activate ligo-py37
 
+
+.. _lscsoft-conda-available-environments:
+
 ----------------------
 Available environments
 ----------------------

docs/environments/list.sh

@@ -4,5 +4,5 @@ CONDA_CMD="conda env list"
 if [ -z "${LSCSOFT_CONDA_DOCKER_IMAGE}" ]; then
     ${CONDA_CMD}
 else
-    docker run ${LSCSOFT_CONDA_DOCKER_IMAGE} ligo-py37 ${CONDA_CMD}
+    docker run ${LSCSOFT_CONDA_DOCKER_IMAGE} ligo-py37 ${CONDA_CMD} | sed 's|/opt/conda|/cvmfs/ligo-containers.opensciencegrid.org/lscsoft/conda/latest|g'
 fi

docs/index.rst

@@ -13,5 +13,6 @@
    :caption: Documentation
    :maxdepth: 2
 
-   usage
+   usage/index
    environments/index
+   tips/index

docs/tips/index.rst

+
+.. _lscsoft-conda-tips:
+
+===============
+Tips and tricks
+===============
+
+--------------------
+Clone an environment
+--------------------
+
+You can clone one of the pre-built environments (or any environment, generally) with
+
+.. code-block:: bash
+
+   conde create --name <target> --clone <source>
+
+e.g.:
+
+.. code-block:: bash
+
+   conda create --name myligo-py37 --clone ligo-py37
+
+--------------------
+Preserve your prompt
+--------------------
+
+By default, activating a conda environment will change your login prompt.
+This behaviour can be disabled with
+
+.. code-block:: bash
+
+   conda config --set changeps1 no

docs/usage.rst → docs/usage/index.rst

+.. _lscsoft-conda-usage:
+
 ===================
 Using LSCSoft Conda
 ===================
 
-**LSCSoft Conda is fully supported on 64-bit Linux and macOS, support for
-other platforms is on a best-effort basis only.**
+.. note::
+
+   LSCSoft Conda is fully supported on 64-bit Linux and macOS, support for
+   other platforms is on a best-effort basis only.
+
+.. note::
+
+   Linux users, especially those using the LIGO Data Grid computing centres,
+   may find it easier to just use one of the
+   :ref:`lscsoft-conda-pre-built-environments`.
 
 ----------------
 1. Install conda
 ----------------
 
-Using software provided by LSCSoft Conda requires the conda package manager.
-We recommend installing `Miniconda <https://conda.io/miniconda.html>`_,
-however you can also install conda
-`using your Linux package manager <https://www.anaconda.com/rpm-and-debian-repositories-for-miniconda/>`_.
+Using software provided by LSCSoft Conda requires the
+`conda <https://conda.io>`_ package manager.
+We recommend `installing Miniconda
+<https://conda.io/projects/conda/en/latest/user-guide/install/index.html>`_,
+however you can also `install conda using your Linux package manager
+<https://www.anaconda.com/rpm-and-debian-repositories-for-miniconda/>`_.
 
 -------------------------------
 2. Add the conda-forge channnel
@@ -24,17 +36,11 @@ All LSCSoft Conda packages are distributed on the conda-forge channnel.
 
    conda config --add channels conda-forge
 
--------------------
-3. Install packages
--------------------
-
-You should now be able to install packages into the current conda environment:
-
-.. code-block:: bash
-
-   conda install gwpy
+------------------------
+3. Create an environment
+------------------------
 
-or you can create a new environment:
+You should now be able to create a conda environment:
 
 .. code-block:: bash