Merge pull request #10 from TGSAI/docs/syntax_improve

Add Install Instructions and Improve README.md

Author: tasansal

README.md

@@ -6,7 +6,7 @@ width=200"><br>
 [![PyPI](https://img.shields.io/pypi/v/multidimio.svg)][pypi_]
 [![Status](https://img.shields.io/pypi/status/multidimio.svg)][status]
 [![Python Version](https://img.shields.io/pypi/pyversions/multidimio)][python version]
-[![License](https://img.shields.io/pypi/l/multidimio)][license]
+[![License](https://img.shields.io/pypi/l/multidimio)][license-link]
 
 [![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]
@@ -29,6 +29,8 @@ The primary motivation behind **MDIO** is to represent multidimensional
 time series data in a format that makes it easier to use in resource assessment,
 machine learning, and data processing workflows.
 
+See the [documentation][read the docs] for more information.
+
 # Features
 
 **Shared Features**
@@ -52,30 +54,20 @@ machine learning, and data processing workflows.
 
 The features marked as **FUTURE** will be open-sourced at a later date.
 
-# Installation
+# Installing MDIO
 
-You can install _MDIO_ via [pip] from [PyPI]:
+Simplest way to install _MDIO_ via [pip] from [PyPI]:
 
 ```shell
 pip install multidimio
 ```
 
-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.
+For more instructions, please see the [installation instructions][read the docs]
+in the documentation.
 
-# Usage
+# Using MDIO
 
-Please see the [Command-line Reference] for details.
+Please see the [Command-line Reference][cli-ref-link] for details.
 
 For Python API please see the [API Reference] for details.
 
@@ -93,14 +85,14 @@ Distributed computing `[distributed]`: `distributed` and `bokeh`.\
 Cloud Object Store I/O `[cloud]`: `s3fs`, `gcsfs`, and `adlfs`.\
 Lossy Compression `[lossy]`: `zfpy`
 
-# Contributing
+# Contributing to MDIO
 
 Contributions are very welcome.
 To learn more, see the [Contributor Guide].
 
-# License
+# Licensing
 
-Distributed under the terms of the [Apache 2.0 license][license],
+Distributed under the terms of the [Apache 2.0 license][license-link],
 _MDIO_ is free and open source software.
 
 # Issues
@@ -136,7 +128,8 @@ template.
 
 <!-- github-only -->
 
-[license]: https://github.com/TGSAI/mdio-python/blob/main/LICENSE
+[license-link]: https://github.com/TGSAI/mdio-python/blob/main/LICENSE
 [contributor guide]: https://github.com/TGSAI/mdio-python/blob/main/CONTRIBUTING.md
-[command-line reference]: https://mdio-python.readthedocs.io/en/latest/usage.html
+[cli-ref-link]: https://mdio-python.readthedocs.io/en/latest/usage.html
 [api reference]: https://mdio-python.readthedocs.io/en/latest/reference.html
+[install-link]: https://mdio-python.readthedocs.io/en/latest/installation.html

docs/conf.py

@@ -5,6 +5,7 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
+    "sphinx.ext.autosectionlabel",
     "sphinx_click",
     "sphinx_copybutton",
     "myst_nb",
@@ -14,13 +15,21 @@
 autodoc_typehints_format = "short"
 autodoc_member_order = "groupwise"
 autoclass_content = "both"
+autosectionlabel_prefix_document = True
 
 html_theme = "furo"
 
+myst_number_code_blocks = ["python"]
 myst_heading_anchors = 2
+myst_enable_extensions = [
+    "linkify",
+    "replacements",
+    "smartquotes",
+]
 
 # sphinx-copybutton configurations
 copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_line_continuation_character = "\\"
 copybutton_prompt_is_regexp = True
 
 nb_execution_mode = "off"

docs/index.md

@@ -13,6 +13,7 @@ end-before: <!-- github-only -->
 hidden:
 maxdepth: 1
 ---
+installation
 notebooks/quickstart
 usage
 reference

docs/installation.md

@@ -0,0 +1,83 @@
+# Install Instructions
+
+There are different ways to install MDIO:
+
+- Install the latest release.
+- Building package from source.
+
+```{note}
+We strongly recommend using a virtual environment `venv` or `conda`
+to avoid potential conflicts with other Python packages.
+```
+
+## Using `pip` and `virtualenv`
+
+Install the 64-bit version of Python 3 from https://www.python.org.
+
+```shell
+$ python -m venv mdio-venv
+$ mdio-venv/Scripts/activate
+$ pip install -U multidimio
+```
+
+## 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.
+```
+
+We first run the following to create and activate an environment:
+
+```shell
+$ conda create -n mdio-env
+$ conda activate mdio-env
+```
+
+Then we need to install with `pip`:
+
+```shell
+$ pip install -U multidimio
+```
+
+The above command will install MDIO into your `conda` environment.
+
+## Checking Installation
+
+After installing MDIO, run the following:
+
+```shell
+$ python -c "import mdio; print(mdio.__version__)"
+```
+
+You should see the version of MDIO printed to the screen.
+
+## Extras
+
+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