docs: repair docs and add very brief quickstart

cmusphinx · Sep 7, 2022 · 9a545b5 · 9a545b5
1 parent 1fcb9ef
commit 9a545b5
Show file tree

Hide file tree

Showing 3 changed files with 39 additions and 9 deletions.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,14 +1,49 @@
 PocketSphinx Documentation
 ============================
 
+Welcome to the documentation for the Python interface to the
+PocketSphinx speech recognizer!
+
+Quick Start
+-----------
+
+To install PocketSphinx on most recent versions of Python, you should
+be able to simply use `pip`::
+
+  pip install pocketsphinx
+
+This is a (somewhat) "batteries-included" install, which comes with a
+default model and dictionary.  Sadly, this model is specifically for
+US (and, by extension Canadian) English, so it may not work well for
+your dialect and certainly won't work for your other language.
+
+On Unix-like platforms you may need to install `PortAudio
+<https://portaudio.com>`_ for live audio input to work.  Now you can
+try the simplest possible speech recognizer::
+
+  from pocketsphinx import LiveSpeech
+  for phrase in LiveSpeech():
+      print(phrase)
+
+This will open the default audio device and start listening, detecting
+segments of speech and printing out the recognized text, which may or
+may not resemble what you actually said.
+
+There are of course many other things you can do with it.  See
+the :ref:`apidoc` for more information.
+
+.. _apidoc:
+
+API Documentation
+-----------------
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
-   readme
    pocketsphinx
    config_params
 
+
 Indices and tables
 ==================
 

diff --git a/docs/source/pocketsphinx5.rst → docs/source/pocketsphinx.rst b/docs/source/pocketsphinx5.rst → docs/source/pocketsphinx.rst
@@ -1,5 +1,5 @@
-pocketsphinx package
-======================
+Main pocketsphinx package
+=========================
 
 .. automodule:: pocketsphinx
 

diff --git a/docs/source/readme.rst b/docs/source/readme.rst