Merge pull request #23 from TGSAI/docs/conda

Add `conda-forge` instructions to docs and update README.md

Author: tasansal

README.md

@@ -1,28 +1,41 @@
 <div>
-  <img src="https://raw.githubusercontent.com/TGSAI/mdio.github.io/gh-pages/assets/images/mdio.png",
-width=200"><br>
+  <img
+      class="logo"
+      src="https://raw.githubusercontent.com/TGSAI/mdio.github.io/gh-pages/assets/images/mdio.png"
+      alt="MDIO"
+      width=200
+      height=auto
+      style="margin-top:10px;margin-bottom:10px"
+  />
 </div>
 
-[![PyPI](https://img.shields.io/pypi/v/multidimio.svg)][pypi_]
-[![Status](https://img.shields.io/pypi/status/multidimio.svg)][status]
+[![PyPI](https://img.shields.io/pypi/v/multidimio.svg)][install_pip]
+[![Conda](https://img.shields.io/conda/vn/conda-forge/multidimio)][install_conda]
 [![Python Version](https://img.shields.io/pypi/pyversions/multidimio)][python version]
+[![Status](https://img.shields.io/pypi/status/multidimio.svg)][status]
 [![License](https://img.shields.io/pypi/l/multidimio)][license]
 
-[![Read the documentation at https://mdio-python.readthedocs.io/](https://img.shields.io/readthedocs/mdio-python/latest.svg?label=Read%20the%20Docs)][read the docs]
 [![Tests](https://github.com/TGSAI/mdio-python/workflows/Tests/badge.svg)][tests]
 [![Codecov](https://codecov.io/gh/TGSAI/mdio-python/branch/main/graph/badge.svg)][codecov]
+[![Read the documentation at https://mdio-python.readthedocs.io/](https://img.shields.io/readthedocs/mdio-python/latest.svg?label=Read%20the%20Docs)][read the docs]
 
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)][pre-commit]
 [![Black](https://img.shields.io/badge/code%20style-black-000000.svg)][black]
 
+[![PyPI Downloads](https://img.shields.io/pypi/dm/multidimio?label=PyPI%20downloads)][pypi_]
+[![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/multidimio?label=Conda%20downloads&style=flat)][conda-forge_]
+
 [pypi_]: https://pypi.org/project/multidimio/
+[conda-forge_]: https://anaconda.org/conda-forge/multidimio
 [status]: https://pypi.org/project/multidimio/
 [python version]: https://pypi.org/project/multidimio
 [read the docs]: https://mdio-python.readthedocs.io/
 [tests]: https://github.com/TGSAI/mdio-python/actions?workflow=Tests
 [codecov]: https://app.codecov.io/gh/TGSAI/mdio-python
 [pre-commit]: https://github.com/pre-commit/pre-commit
 [black]: https://github.com/psf/black
+[install_pip]: https://mdio-python.readthedocs.io/en/latest/installation.html#using-pip-and-virtualenv
+[install_conda]: https://mdio-python.readthedocs.io/en/latest/installation.html#using-conda
 
 **_"MDIO"_** is a library to work with large multidimensional energy datasets.
 The primary motivation behind **MDIO** is to represent multidimensional
@@ -59,10 +72,20 @@ The features marked as **FUTURE** will be open-sourced at a later date.
 Simplest way to install _MDIO_ via [pip] from [PyPI]:
 
 ```shell
-pip install multidimio
+$ pip install multidimio
+```
+
+or install _MDIO_ via [conda] from [conda-forge]:
+
+```shell
+$ conda install -c conda-forge multidimio
+```
+
+```{note}
+Extras must be installed separately on `Conda` environments.
 ```
 
-For more instructions, please see the [installation instructions][install]
+For details, please see the [installation instructions][install]
 in the documentation.
 
 # Using MDIO
@@ -112,9 +135,11 @@ template.
 
 [@cjolowicz]: https://github.com/cjolowicz
 [pypi]: https://pypi.org/
+[conda-forge]: https://conda-forge.org/
 [hypermodern python cookiecutter]: https://github.com/cjolowicz/cookiecutter-hypermodern-python
 [file an issue]: https://github.com/TGSAI/mdio-python/issues
 [pip]: https://pip.pypa.io/
+[conda]: https://docs.conda.io/
 [dask]: https://www.dask.org/
 [zarr]: https://zarr.dev/
 [fsspec]: https://filesystem-spec.readthedocs.io/en/latest/

docs/installation.md

@@ -2,8 +2,8 @@
 
 There are different ways to install MDIO:
 
-- Install the latest release.
-- Building package from source.
+- Install the latest release via [`pip`](#using-pip-and-virtualenv) or [`conda`](#using-conda).
+- Building package [from source](#building-from-source).
 
 ```{note}
 We strongly recommend using a virtual environment `venv` or `conda`
@@ -14,25 +14,44 @@ to avoid potential conflicts with other Python packages.
 
 Install the 64-bit version of Python 3 from https://www.python.org.
 
+Then we can create a `venv` and install _MDIO_.
+
 ```shell
 $ python -m venv mdio-venv
 $ mdio-venv/Scripts/activate
 $ pip install -U multidimio
 ```
 
+To check if installation was successful see [checking installation](#checking-installation).
+
+You can also install some optional dependencies (extras) like this:
+
+```shell
+$ pip install multidimio[distributed]
+$ pip install multidimio[cloud]
+$ pip install multidimio[lossy]
+```
+
+`distributed` installs [Dask][dask] for parallel, distributed processing.\
+`cloud` installs [fsspec][fsspec] backed I/O libraries for [AWS' S3][s3fs],
+[Google's GCS][gcsfs], and [Azure ABS][adlfs].\
+`lossy` will install the [ZFPY][zfp] library for lossy chunk compression.
+
+[dask]: https://www.dask.org/
+[fsspec]: https://filesystem-spec.readthedocs.io/en/latest/
+[s3fs]: https://s3fs.readthedocs.io/
+[gcsfs]: https://gcsfs.readthedocs.io/
+[adlfs]: https://github.com/fsspec/adlfs
+[zfp]: https://computing.llnl.gov/projects/zfp
+
 ## Using `conda`
 
 MDIO can also be installed in a `conda` environment.
 
-```{warning}
-Native `conda` installation for MDIO is work-in-progress. Due to the bundled
-packages with the [Anaconda](https://www.anaconda.com/products/distribution)
-distrtibution, installing MDIO using `pip` into the `conda` environment will
-cause your environment to break.
-
-In the meantime, please use the
-[Miniconda](https://docs.conda.io/en/latest/miniconda.html) distribution which
-doesn't come with bundled packages.
+```{note}
+_MDIO_ is hosted in the `conda-forge` channel. Make sure to always provide the
+`-c conda-forge` when running `conda install` or else it won't be able to find
+the package.
 ```
 
 We first run the following to create and activate an environment:
@@ -42,14 +61,18 @@ $ conda create -n mdio-env
 $ conda activate mdio-env
 ```
 
-Then we need to install with `pip`:
+Then we can to install with `conda`:
 
 ```shell
-$ pip install -U multidimio
+$ conda install -c conda-forge multidimio
 ```
 
 The above command will install MDIO into your `conda` environment.
 
+```{note}
+_MDIO_ extras must be installed separately when using `conda`.
+```
+
 ## Checking Installation
 
 After installing MDIO, run the following:
@@ -60,24 +83,28 @@ $ python -c "import mdio; print(mdio.__version__)"
 
 You should see the version of MDIO printed to the screen.
 
-## Extras
+## Building from Source
 
-You can also install some optional dependencies (extras) like this:
+All dependencies of _MDIO_ are Python packages, so the build process is very simple.
+To install from source, we need to clone the repo first and then install locally via `pip`.
 
 ```shell
-$ pip install multidimio[distributed]
-$ pip install multidimio[cloud]
-$ pip install multidimio[lossy]
+$ git clone https://github.com/TGSAI/mdio-python.git
+$ cd mdio-python
+$ pip install .
 ```
 
-`distributed` installs [Dask][dask] for parallel, distributed processing.\
-`cloud` installs [fsspec][fsspec] backed I/O libraries for [AWS' S3][s3fs],
-[Google's GCS][gcsfs], and [Azure ABS][adlfs].\
-`lossy` will install the [ZFPY][zfp] library for lossy chunk compression.
+We can also install the extras in a similar way, for example:
 
-[dask]: https://www.dask.org/
-[fsspec]: https://filesystem-spec.readthedocs.io/en/latest/
-[s3fs]: https://s3fs.readthedocs.io/
-[gcsfs]: https://gcsfs.readthedocs.io/
-[adlfs]: https://github.com/fsspec/adlfs
-[zfp]: https://computing.llnl.gov/projects/zfp
+```shell
+$ pip install .[cloud]
+```
+
+If you want an editable version of _MDIO_ then we could install it with the command below.
+This does allow you to make code changes on the fly.
+
+```shell
+$ pip install --editable .[cloud]
+```
+
+To check if installation was successful see [checking installation](#checking-installation).