Commit 3b1cf8e1 authored by Duncan Macleod's avatar Duncan Macleod

Merge branch 'docs2' into 'master'

Updated docs

Closes #5

See merge request lscsoft/conda!22
parents e1fe4965 9895ea73
Pipeline #49942 passed with stages
in 69 minutes and 46 seconds
...@@ -76,6 +76,8 @@ docs: ...@@ -76,6 +76,8 @@ docs:
script: script:
- cd docs - cd docs
- python3 -m sphinx -M html . ../build/sphinx -vv - 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: artifacts:
paths: paths:
- build/sphinx/html - build/sphinx/html
......
...@@ -17,19 +17,42 @@ using the `conda <https://conda.io>`_ package manager, and the ...@@ -17,19 +17,42 @@ using the `conda <https://conda.io>`_ package manager, and the
Quickstart 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: 2. Add the conda-forge channel:
:: .. code-block:: bash
conda config --add channels conda-forge 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 Contributing
============ ============
......
.. _lscsoft-conda-reference-environments:
====================== ======================
Reference environments Reference environments
====================== ======================
The LSCSoft Conda team currently defines reference environments for a number 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 You can install these by downloading the relevant YAML file from the repository
and installing them. and installing them.
.. _lscsoft-conda-pre-built-environments:
---------------------- ----------------------
Pre-built environments Pre-built environments
---------------------- ----------------------
...@@ -35,6 +40,9 @@ You can then activate one of these environments: ...@@ -35,6 +40,9 @@ You can then activate one of these environments:
conda activate ligo-py37 conda activate ligo-py37
.. _lscsoft-conda-available-environments:
---------------------- ----------------------
Available environments Available environments
---------------------- ----------------------
......
...@@ -4,5 +4,5 @@ CONDA_CMD="conda env list" ...@@ -4,5 +4,5 @@ CONDA_CMD="conda env list"
if [ -z "${LSCSOFT_CONDA_DOCKER_IMAGE}" ]; then if [ -z "${LSCSOFT_CONDA_DOCKER_IMAGE}" ]; then
${CONDA_CMD} ${CONDA_CMD}
else 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 fi
...@@ -13,5 +13,6 @@ ...@@ -13,5 +13,6 @@
:caption: Documentation :caption: Documentation
:maxdepth: 2 :maxdepth: 2
usage usage/index
environments/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 Using LSCSoft Conda
=================== ===================
**LSCSoft Conda is fully supported on 64-bit Linux and macOS, support for .. note::
other platforms is on a best-effort basis only.**
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 1. Install conda
---------------- ----------------
Using software provided by LSCSoft Conda requires the conda package manager. Using software provided by LSCSoft Conda requires the
We recommend installing `Miniconda <https://conda.io/miniconda.html>`_, `conda <https://conda.io>`_ package manager.
however you can also install conda We recommend `installing Miniconda
`using your Linux package manager <https://www.anaconda.com/rpm-and-debian-repositories-for-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 2. Add the conda-forge channnel
...@@ -24,17 +36,11 @@ All LSCSoft Conda packages are distributed on 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 conda config --add channels conda-forge
------------------- ------------------------
3. Install packages 3. Create an environment
------------------- ------------------------
You should now be able to install packages into the current conda environment:
.. code-block:: bash
conda install gwpy
or you can create a new environment: You should now be able to create a conda environment:
.. code-block:: bash .. 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