update installation doc for k2-fsa/sherpa (#443)

k2-fsa · Jul 25, 2023 · 1a5d9f3 · 1a5d9f3
1 parent 2744ef6
commit 1a5d9f3
Show file tree

Hide file tree

Showing 6 changed files with 382 additions and 269 deletions.
diff --git a/docs/source/cpu.html b/docs/source/cpu.html
diff --git a/docs/source/cuda.html b/docs/source/cuda.html
diff --git a/docs/source/sherpa/install/check_your_installation.rst b/docs/source/sherpa/install/check_your_installation.rst
@@ -0,0 +1,29 @@
+.. _check_sherpa_installation:
+
+Check your installation
+=======================
+
+To check that you have installed ``k2-fsa/sherpa`` successfully, please run:
+
+.. code-block:: bash
+
+   python3 -c "import sherpa; print(sherpa.__file__); print(sherpa.__version__)"
+
+   sherpa-online --help
+   sherpa-offline --help
+
+   sherpa-online-microphone --help
+   sherpa-offline-microphone --help
+
+   sherpa-online-websocket-server --help
+   sherpa-online-websocket-client --help
+   sherpa-online-websocket-client-microphone --help
+
+   sherpa-offline-websocket-server --help
+   sherpa-offline-websocket-client --help
+
+
+Congratulations! You have installed `k2-fsa/sherpa`_ successfully. Please
+refer to :ref:`k2_fsa_sherpa_pretrained_models` to download pre-trained models.
+
+Have fun with `k2-fsa/sherpa`_!
diff --git a/docs/source/sherpa/install/from_source.rst b/docs/source/sherpa/install/from_source.rst
@@ -0,0 +1,108 @@
+.. _install_sherpa_from_source:
+
+From source
+===========
+
+This section describe how to install ``k2-fsa/sherpa`` from source.
+
+
+Install dependencies
+--------------------
+
+Before installing ``k2-fsa/sherpa`` from source, we have to install the following
+dependencies.
+
+  - `PyTorch`_
+  - `k2`_
+  - `kaldifeat`_
+
+.. tabs::
+
+   .. tab:: CPU
+
+     Suppose that we select ``torch==2.0.1``. We can use the following
+     commands to install the dependencies:
+
+     .. tabs::
+
+       .. tab:: Linux
+
+        .. code-block:: bash
+
+           pip install torch==2.0.1+cpu -f https://download.pytorch.org/whl/torch_stable.html
+           pip install k2==1.24.3.dev20230719+cpu.torch2.0.1 -f https://k2-fsa.github.io/k2/cpu.html
+           pip install kaldifeat==1.24.dev20230724+cpu.torch2.0.1 -f https://csukuangfj.github.io/kaldifeat/cpu.html
+
+       .. tab:: macOS
+
+        .. code-block:: bash
+
+           pip install torch==2.0.1+cpu -f https://download.pytorch.org/whl/torch_stable.html
+           pip install k2==1.24.3.dev20230720+cpu.torch2.0.1 -f https://k2-fsa.github.io/k2/cpu.html
+           pip install kaldifeat==1.24.dev20230724+cpu.torch2.0.1 -f https://csukuangfj.github.io/kaldifeat/cpu.html
+
+       .. tab:: Windows
+
+        To be done.
+
+   .. tab:: CUDA
+
+     Suppose that we select ``torch==2.0.1+cu117``. We can use the following
+     commands to install the dependencies:
+
+      .. code-block:: bash
+
+         pip install torch==2.0.1+cu117 -f https://download.pytorch.org/whl/torch_stable.html
+         pip install k2==1.24.3.dev20230718+cuda11.7.torch2.0.1 -f https://k2-fsa.github.io/k2/cuda.html
+         pip install kaldifeat==1.24.dev20230724+cuda11.7.torch2.0.1  -f https://csukuangfj.github.io/kaldifeat/cuda.html
+
+     Next, please follow `<https://k2-fsa.github.io/k2/installation/cuda-cudnn.html>`_ to install CUDA toolkit.
+
+Now we can start to build ``k2-fsa/sherpa`` from source.
+
+For general users
+-----------------
+
+You can use the following commands to install `k2-fsa/sherpa`_:
+
+.. code-block:: bash
+
+   # Please make sure you have installed PyTorch, k2, and kaldifeat
+   # before you continue
+   #
+   git clone http://github.com/k2-fsa/sherpa
+   cd sherpa
+   python3 -m pip install --verbose .
+
+To uninstall `k2-fsa/sherpa`_, please use
+
+.. code-block:: bash
+
+   # Please run it outside of the k2-fsa/sherpa repo
+   #
+   pip uninstall k2-sherpa
+
+Please see :ref:`check_sherpa_installation`.
+
+For developers and advanced users
+---------------------------------
+
+You can also use the following commands to install `k2-fsa/sherpa`_.
+
+The advantage is that you can have several versions of `k2-fsa/sherpa`_
+in a single environment.
+
+.. code-block:: bash
+
+   git clone http://github.com/k2-fsa/sherpa
+   cd sherpa
+   mkdir build
+   cd build
+   cmake ..
+   make -j
+
+   export PATH=$PWD/bin:$PATH
+   export PYTHONPATH=$PWD/lib:$PWD/../sherpa/python:$PYTHONPATH
+
+Please see :ref:`check_sherpa_installation`.
+
diff --git a/docs/source/sherpa/install/from_wheels.rst b/docs/source/sherpa/install/from_wheels.rst
@@ -0,0 +1,93 @@
+.. _install_sherpa_from_pre_compiled_wheels:
+
+From pre-compiled wheels
+========================
+
+.. note::
+
+   This method supports only Linux and macOS for now. If you want to
+   use Windows, please refer to :ref:`install_sherpa_from_source`.
+
+You can find a list of pre-compiled wheels at the following URLs:
+
+  - CPU: `<https://k2-fsa.github.io/sherpa/cpu.html>`_
+  - CUDA: `<https://k2-fsa.github.io/sherpa/cuda.html>`_
+
+In the following, we demonstrate how to install ``k2-fsa/sherpa`` from
+pre-compiled wheels.
+
+Linux (CPU)
+-----------
+
+Suppose that we want to install the following wheel
+
+.. code-block:: bash
+
+   https://huggingface.co/csukuangfj/kaldifeat/resolve/main/ubuntu-cpu/k2_sherpa-1.3.dev20230725+cpu.torch2.0.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
+
+we can use the following methods:
+
+.. code-block:: bash
+
+   # Before installing k2-fsa/sherpa, we have to install the following dependencies:
+   #  torch, k2, and kaldifeat
+
+   pip install torch==2.0.1+cpu -f https://download.pytorch.org/whl/torch_stable.html
+   pip install k2==1.24.3.dev20230719+cpu.torch2.0.1 -f https://k2-fsa.github.io/k2/cpu.html
+   pip install kaldifeat==1.24.dev20230724+cpu.torch2.0.1 -f https://csukuangfj.github.io/kaldifeat/cpu.html
+
+   # Now we can install k2-fsa/sherpa
+   pip install k2_sherpa==1.3.dev20230725+cpu.torch2.0.1 -f https://k2-fsa.github.io/sherpa/cpu.html
+
+Please see :ref:`check_sherpa_installation`.
+
+macOS (CPU)
+-----------
+
+Suppose that we want to install the following wheel
+
+.. code-block:: bash
+
+   https://huggingface.co/csukuangfj/kaldifeat/resolve/main/macos/k2_sherpa-1.3.dev20230725+cpu.torch2.0.1-cp311-cp311-macosx_10_9_x86_64.whl
+
+we can use the following methods:
+
+.. code-block:: bash
+
+   # Before installing k2-fsa/sherpa, we have to install the following dependencies:
+   #  torch, k2, and kaldifeat
+
+   pip install torch==2.0.1+cpu -f https://download.pytorch.org/whl/torch_stable.html
+   pip install k2==1.24.3.dev20230720+cpu.torch2.0.1 -f https://k2-fsa.github.io/k2/cpu.html
+   pip install kaldifeat==1.24.dev20230724+cpu.torch2.0.1 -f https://csukuangfj.github.io/kaldifeat/cpu.html
+
+   # Now we can install k2-fsa/sherpa
+   pip install k2_sherpa==1.3.dev20230725+cpu.torch2.0.1 -f https://k2-fsa.github.io/sherpa/cpu.html
+
+Please see :ref:`check_sherpa_installation`.
+
+Linux (CUDA)
+------------
+
+Suppose that we want to install the following wheel
+
+.. code-block:: bash
+
+   https://huggingface.co/csukuangfj/kaldifeat/resolve/main/ubuntu-cuda/k2_sherpa-1.3.dev20230725+cuda11.7.torch2.0.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
+
+we can use the following methods:
+
+.. code-block:: bash
+
+   # Before installing k2-fsa/sherpa, we have to install the following dependencies:
+   #  torch, k2, and kaldifeat
+
+   pip install torch==2.0.1+cu117 -f https://download.pytorch.org/whl/torch_stable.html
+   pip install k2==1.24.3.dev20230718+cuda11.7.torch2.0.1 -f https://k2-fsa.github.io/k2/cuda.html
+   pip install kaldifeat==1.24.dev20230724+cuda11.7.torch2.0.1  -f https://csukuangfj.github.io/kaldifeat/cuda.html
+
+
+   # Now we can install k2-fsa/sherpa
+   pip install k2_sherpa==1.3.dev20230725+cuda11.7.torch2.0.1 -f https://k2-fsa.github.io/sherpa/cuda.html
+
+Please see :ref:`check_sherpa_installation`.
diff --git a/docs/source/sherpa/install/index.rst b/docs/source/sherpa/install/index.rst
@@ -3,132 +3,15 @@
 Installation
 ============
 
-Requirements
-------------
+.. toctree::
+   :maxdepth: 3
 
-Before installing `k2-fsa/sherpa`_, we assume you have installed:
+   ./from_wheels.rst
+   ./from_source.rst
+   ./check_your_installation.rst
 
-- `PyTorch`_
-- `k2`_
-- `kaldifeat`_
-
-
-Normal
-------
-
-You can use the following commands to install `k2-fsa/sherpa`_:
-
-.. code-block:: bash
-
-   # Please make sure you have installed PyTorch, k2, and kaldifeat
-   # before you continue
-   #
-   git clone http://github.com/k2-fsa/sherpa
-   cd sherpa
-   python3 -m pip install --verbose .
-
-The above commands install the Python package ``k2-sherpa`` as well as
-generated ``executables``.
-
-.. hint::
-
-   Please don't use ``python3 setup.py install``.
-
-   Use ``python3 -m pip install --verbose .`` instead.
-
-To check that you have installed `k2-fsa/sherpa`_ successfully, please run:
-
-.. code-block:: bash
-
-   # Test for Python
-   #
-   python3 -c "import sherpa; print(sherpa.__file__)"
-   python3 -c "import sherpa; print(sherpa.__version__)"
-
-   # Test for generated executables
-   #
-   which sherpa-version
-   sherpa-version
-
-   which sherpa-online
-   sherpa-online --help
-
-   which sherpa-offline
-   sherpa-offline --help
-
-   which sherpa-online-microphone
-   sherpa-online-microphone --help
-
-   which sherpa-offline-microphone
-   sherpa-offline-microphone --help
-
-   which sherpa-online-websocket-server
-   sherpa-online-websocket-server --help
-
-   which sherpa-online-websocket-client
-   sherpa-online-websocket-client --help
-
-   which sherpa-online-websocket-client-microphone
-   sherpa-online-websocket-client-microphone --help
-
-   which sherpa-offline-websocket-server
-   sherpa-offline-websocket-server --help
-
-   which sherpa-offline-websocket-client
-   sherpa-offline-websocket-client --help
-
-
-To uninstall `k2-fsa/sherpa`_, please use
-
-.. code-block:: bash
-
-   # Please run it outside of the k2-fsa/sherpa repo
-   #
-   pip uninstall k2-sherpa
-
-For developers and advanced users
----------------------------------
-
-You can also use the following commands to install `k2-fsa/sherpa`_.
-
-The advantage is that you can have several versions of `k2-fsa/sherpa`_
-in a single environment.
-
-.. code-block:: bash
-
-   git clone http://github.com/k2-fsa/sherpa
-   cd sherpa
-   mkdir build
-   cd build
-   cmake ..
-   make -j
-
-   export PATH=$PWD/bin:$PATH
-   export PYTHONPATH=$PWD/lib:$PWD/../sherpa/python:$PYTHONPATH
-
-To test that you have installed `k2-fsa/sherpa`_ successfully, you can run the
-following commands:
-
-.. code-block:: bash
-
-   cd /path/to/sherpa/build
-
-   python3 -c "import sherpa; print(sherpa.__file__)"
-
-   ./bin/sherpa-version
-
-   ./bin/sherpa-offline --help
-   ./bin/sherpa-online --help
-
-   ./bin/sherpa-online-microphone --help
-   ./bin/sherpa-offline-microphone --help
-
-   ./bin/sherpa-offline-websocket-server --help
-   ./bin/sherpa-offline-websocket-client --help
-
-   ./bin/sherpa-online-websocket-server --help
-   ./bin/sherpa-online-websocket-client --help
-   ./bin/sherpa-online-websocket-client-microphone --help
+We suggest that you install ``k2-fsa/sherpa`` by following
+:ref:`install_sherpa_from_pre_compiled_wheels`.
 
 Where to get help
 -----------------