From 9345b787574350befabc30195747637706f82460 Mon Sep 17 00:00:00 2001
From: Wu-Jung Lee <leewujung@gmail.com>
Date: Tue, 10 Sep 2024 14:43:06 +0000
Subject: [PATCH] Update installation doc page (#1389)

* update installation page, convert from rst to md

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* add hyperlink on contributing.md

* remove horizontal lines

* fix small typos

* specify python 3.12

Co-authored-by: Caesar Tuguinay <87830138+ctuguinay@users.noreply.github.com>

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Caesar Tuguinay <87830138+ctuguinay@users.noreply.github.com>
---
 docs/source/contributing.md  |  1 +
 docs/source/installation.md  | 37 ++++++++++++++++++++++++++++++++++
 docs/source/installation.rst | 39 ------------------------------------
 3 files changed, 38 insertions(+), 39 deletions(-)
 create mode 100644 docs/source/installation.md
 delete mode 100644 docs/source/installation.rst

diff --git a/docs/source/contributing.md b/docs/source/contributing.md
index d31161740..7fca175f4 100644
--- a/docs/source/contributing.md
+++ b/docs/source/contributing.md
@@ -1,3 +1,4 @@
+(contributing)=
 # Contributing to echopype
 
 
diff --git a/docs/source/installation.md b/docs/source/installation.md
new file mode 100644
index 000000000..cc88e2c84
--- /dev/null
+++ b/docs/source/installation.md
@@ -0,0 +1,37 @@
+# Installation and examples
+
+## Installation
+
+Echopype is available and tested for Python 3.9-3.11. The latest release can be installed through conda (or mamba, see below) via the [conda-forge channel](https://anaconda.org/conda-forge/echopype):
+```shell
+# Install via conda-forge
+$ conda install -c conda-forge echopype
+```
+
+It is available via [PyPI](https://pypi.org/project/echopype):
+```shell
+# Install via pip
+$ pip install echopype
+```
+
+:::{note}
+We are working on adding support for Python 3.12 soon!
+:::
+
+:::{attention}
+It's common to encounter the situation that installing packages using Conda is slow or fails,
+because Conda is unable to resolve dependencies.
+We suggest using Mamba to get around this.
+See [Mamba's documentation](https://mamba.readthedocs.io/en/latest/) for installation and usage.
+One can replace `conda` with `mamba` in the above commands when creating the environment and installing additional packages.
+:::
+
+Previous releases are also available on conda and PyPI.
+
+For instructions on installing a development version of echopype,
+see the [](contributing) page.
+
+
+## Example notebooks
+
+The [echopype-examples](https://github.com/OSOceanAcoustics/echopype-examples) repository contains multiple Jupyter notebook examples illustrating the Echopype workflow. See the [rendered pages](https://echopype-examples.readthedocs.io/) before trying them out!
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
deleted file mode 100644
index e36e885f4..000000000
--- a/docs/source/installation.rst
+++ /dev/null
@@ -1,39 +0,0 @@
-Installation and Examples
-=========================
-
-
-Installation
-------------
-
-Echopype is available and tested for Python>=3.9. The latest release
-can be installed from `PyPI <https://pypi.org/project/echopype/>`_:
-
-.. code-block:: console
-
-   $ pip install echopype
-
-or through conda from the `conda-forge Anaconda channel <https://anaconda.org/conda-forge/echopype>`_:
-
-.. code-block:: console
-
-   $ conda install -c conda-forge echopype
-
-.. attention::
-   We recommend using the ``libmamba`` solver instead of the classic solver.
-   See instructions `here <https://conda.github.io/conda-libmamba-solver/getting-started/>`_
-   for installation and usage.
-
-Previous releases are also available on PyPI and conda.
-
-For instructions on installing a development version of echopype,
-see the :doc:`contributing` page.
-
-
-Examples
---------
-
-Additional `Jupyter notebooks <https://osoceanacoustics.github.io/echopype-examples/>`_
-illustrating the workflow of Echopype are also made available. These
-examples include a quick tour of Echopype, a demonstration of how Echopype can be used
-to explore ship echosounder data from a Pacific Hake survey, and using Echopype to
-visualize the response of zooplankton to a solar eclipse.