[doc] add tutorial for kaldi pybind IO. (#3986)

Author: csukuangfj

src/pybind/.clang-format

@@ -0,0 +1,4 @@
+# Run manually to reformat a file:
+# clang-format -i --style=file <file>
+BasedOnStyle: Google
+DerivePointerAlignment: false

src/pybind/doc/conf.py

@@ -18,27 +18,25 @@
 # otherwise `import` will throw.
 import sphinx_rtd_theme
 
-
-
 # -- Project information -----------------------------------------------------
 
 project = 'Kaldi Pybind'
-copyright = '2020, Kaldi Pybind Authors'
+copyright = '2019-2020, Kaldi Pybind Authors'
 author = 'Kaldi Pybind Authors'
 
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-'sphinx.ext.autodoc',
-'sphinx.ext.autosummary',
-'sphinx.ext.mathjax',
-'sphinx.ext.napoleon',
-'sphinx.ext.todo',
-'sphinx.ext.viewcode',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -60,7 +58,6 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

src/pybind/doc/getting_started.rst

@@ -15,7 +15,7 @@ from
 
     Kaldi Pybind is still under active development and has not
     yet been merged into the master branch. You should checkout
-    the `pybind11` branch before compilation.
+    the ``pybind11`` branch before compilation.
 
 .. Note::
 
@@ -40,3 +40,15 @@ The following is a quick start:
     make
     make test
 
+After a successful compilation, you have to modify the environment
+variable ``PYTHONPATH``:
+
+.. code-block:: bash
+
+  export KALDI_ROOT=/path/to/your/kaldi
+  export PYTHONPATH=$KALDI_ROOT/src/pybind:$PYTHONPATH
+
+.. HINT::
+
+  There is no ``make install``. Once compiled, you are ready to
+  use Kaldi Pybind.

src/pybind/doc/index.rst

@@ -18,3 +18,10 @@ Welcome to Kaldi Pybind's documentation!
 
    introduction
    getting_started
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Tutorial
+
+    tutorial/working_with_kaldi_matrices
+    tutorial/working_with_kaldi_io

src/pybind/doc/introduction.rst

@@ -10,7 +10,7 @@ About Kaldi Pybind
 
 Kaldi Pybind is a Python wrapper for Kaldi
 using `Pybind11 <https://github.com/pybind/pybind11>`_.
+It is still under active development.
 
-Kaldi Pybind is still under active development.
 Everything related to Kaldi Pybind is put in the
 `pybind11 branch <https://github.com/kaldi-asr/kaldi/tree/pybind11>`_.

src/pybind/doc/tutorial/code/test_float_matrix.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+
+import kaldi
+
+f = kaldi.FloatMatrix(2, 3)
+f[1, 2] = 100
+print(f)
+
+g = f.numpy()
+g[0, 0] = 200
+print(f)

src/pybind/doc/tutorial/code/test_float_submatrix.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+
+import kaldi
+import numpy as np
+
+m = np.array([[1, 2, 3], [10, 20, 30]], dtype=np.float32)
+f = kaldi.FloatSubMatrix(m)
+
+f[1, 2] = 100
+print(m)
+print()
+
+g = f.numpy()
+g[0, 0] = 200
+print(m)

src/pybind/doc/tutorial/code/test_float_subvector.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+
+import kaldi
+import numpy as np
+
+v = np.array([10, 20, 30], dtype=np.float32)
+f = kaldi.FloatSubVector(v)
+
+f[0] = 0
+print(v)
+
+g = f.numpy()
+g[1] = 100
+print(v)

src/pybind/doc/tutorial/code/test_float_vector.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+
+import kaldi
+
+f = kaldi.FloatVector(3)
+f[0] = 10
+print(f)
+
+g = f.numpy()
+g[1] = 20
+print(f)

src/pybind/doc/tutorial/code/test_io_ali.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+
+import kaldi
+
+wspecifier = 'ark,scp:/tmp/ali.ark,/tmp/ali.scp'
+
+writer = kaldi.IntVectorWriter(wspecifier)
+writer.Write(key='foo', value=[1, 2, 3])
+writer.Write('bar', [10, 20])
+writer.Close()
+
+rspecifier = 'scp:/tmp/ali.scp'
+reader = kaldi.SequentialIntVectorReader(rspecifier)
+
+for key, value in reader:
+    print(key, value)
+
+reader.Close()
+
+reader = kaldi.RandomAccessIntVectorReader(rspecifier)
+value1 = reader['foo']
+print(value1)
+
+value2 = reader['bar']
+print(value2)
+reader.Close()