updated docs

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

fixes #5
parent 66932359
......@@ -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
......
......@@ -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
============
......
.. _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
----------------------
......
......@@ -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
......@@ -13,5 +13,6 @@
:caption: Documentation
:maxdepth: 2
usage
usage/index
environments/index
tips/index
.. _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
.. _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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment