Skip to content

Commit

Permalink
Docs centered on ReadTheDocs instead of GitHub
Browse files Browse the repository at this point in the history
  • Loading branch information
@reuben
reuben committed Apr 27, 2020
1 parent 6e9b251 commit 1acbed9
Show file tree
Hide file tree
Showing 7 changed files with 67 additions and 92 deletions.
80 changes: 4 additions & 76 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,82 +14,10 @@ Project DeepSpeech

DeepSpeech is an open source Speech-To-Text engine, using a model trained by machine learning techniques based on `Baidu's Deep Speech research paper <https://arxiv.org/abs/1412.5567>`_. Project DeepSpeech uses Google's `TensorFlow <https://www.tensorflow.org/>`_ to make the implementation easier.

**NOTE:** This documentation applies to the **master version** of DeepSpeech only. **Documentation for all versions** is published on `deepspeech.readthedocs.io <http://deepspeech.readthedocs.io/?badge=latest>`_.
Documentation for installation, usage, and training models is available on `deepspeech.readthedocs.io <http://deepspeech.readthedocs.io/?badge=latest>`_.

To install and use DeepSpeech all you have to do is:
For the latest release, including pre-trained models and checkpoints, `see the latest release on GitHub <https://github.com/mozilla/DeepSpeech/releases/latest>`_.

.. code-block:: bash
For contribution guidelines, see `CONTRIBUTING.rst <CONTRIBUTING.rst>`_.

# Create and activate a virtualenv
virtualenv -p python3 $HOME/tmp/deepspeech-venv/
source $HOME/tmp/deepspeech-venv/bin/activate
# Install DeepSpeech
pip3 install deepspeech
# Download pre-trained English model files
curl -LO https://github.com/mozilla/DeepSpeech/releases/download/v0.7.0/deepspeech-0.7.0-models.pbmm
curl -LO https://github.com/mozilla/DeepSpeech/releases/download/v0.7.0/deepspeech-0.7.0-models.scorer
# Download example audio files
curl -LO https://github.com/mozilla/DeepSpeech/releases/download/v0.7.0/audio-0.7.0.tar.gz
tar xvf audio-0.7.0.tar.gz
# Transcribe an audio file
deepspeech --model deepspeech-0.7.0-models.pbmm --scorer deepspeech-0.7.0-models.scorer --audio audio/2830-3980-0043.wav
A pre-trained English model is available for use and can be downloaded using `the instructions below <doc/USING.rst#using-a-pre-trained-model>`_. A package with some example audio files is available for download in our `release notes <https://github.com/mozilla/DeepSpeech/releases/latest>`_.

Quicker inference can be performed using a supported NVIDIA GPU on Linux. See the `release notes <https://github.com/mozilla/DeepSpeech/releases/latest>`_ to find which GPUs are supported. To run ``deepspeech`` on a GPU, install the GPU specific package:

.. code-block:: bash
# Create and activate a virtualenv
virtualenv -p python3 $HOME/tmp/deepspeech-gpu-venv/
source $HOME/tmp/deepspeech-gpu-venv/bin/activate
# Install DeepSpeech CUDA enabled package
pip3 install deepspeech-gpu
# Transcribe an audio file.
deepspeech --model deepspeech-0.7.0-models.pbmm --scorer deepspeech-0.7.0-models.scorer --audio audio/2830-3980-0043.wav
Please ensure you have the required `CUDA dependencies <doc/USING.rst#cuda-dependency>`_.

See the output of ``deepspeech -h`` for more information on the use of ``deepspeech``. (If you experience problems running ``deepspeech``\ , please check `required runtime dependencies <native_client/README.rst#required-dependencies>`_\ ).

----

**Table of Contents**

* `Using a Pre-trained Model <doc/USING.rst#using-a-pre-trained-model>`_

* `CUDA dependency <doc/USING.rst#cuda-dependency>`_
* `Getting the pre-trained model <doc/USING.rst#getting-the-pre-trained-model>`_
* `Model compatibility <doc/USING.rst#model-compatibility>`_
* `Using the Python package <doc/USING.rst#using-the-python-package>`_
* `Using the Node.JS package <doc/USING.rst#using-the-nodejs-package>`_
* `Using the Command Line client <doc/USING.rst#using-the-command-line-client>`_
* `Installing bindings from source <doc/USING.rst#installing-bindings-from-source>`_
* `Third party bindings <doc/USING.rst#third-party-bindings>`_


* `Trying out DeepSpeech with examples <examples/README.rst>`_

* `Training your own Model <doc/TRAINING.rst#training-your-own-model>`_

* `Prerequisites for training a model <doc/TRAINING.rst#prerequisites-for-training-a-model>`_
* `Getting the training code <doc/TRAINING.rst#getting-the-training-code>`_
* `Installing Python dependencies <doc/TRAINING.rst#installing-python-dependencies>`_
* `Recommendations <doc/TRAINING.rst#recommendations>`_
* `Common Voice training data <doc/TRAINING.rst#common-voice-training-data>`_
* `Training a model <doc/TRAINING.rst#training-a-model>`_
* `Checkpointing <doc/TRAINING.rst#checkpointing>`_
* `Exporting a model for inference <doc/TRAINING.rst#exporting-a-model-for-inference>`_
* `Exporting a model for TFLite <doc/TRAINING.rst#exporting-a-model-for-tflite>`_
* `Making a mmap-able model for inference <doc/TRAINING.rst#making-a-mmap-able-model-for-inference>`_
* `Continuing training from a release model <doc/TRAINING.rst#continuing-training-from-a-release-model>`_
* `Training with Augmentation <doc/TRAINING.rst#training-with-augmentation>`_

* `Contribution guidelines <CONTRIBUTING.rst>`_
* `Contact/Getting Help <SUPPORT.rst>`_
For contact and support information, see `SUPPORT.rst <SUPPORT.rst>`_.
12 changes: 4 additions & 8 deletions SUPPORT.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,10 @@ Contact/Getting Help
There are several ways to contact us or to get help:


#.
`\ **FAQ** <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_ - We have a list of common questions, and their answers, in our `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_. When just getting started, it's best to first check the `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_ to see if your question is addressed.
#. `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_ - We have a list of common questions, and their answers, in our `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_. When just getting started, it's best to first check the `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_ to see if your question is addressed.

#.
`\ **Discourse Forums** <https://discourse.mozilla.org/c/deep-speech>`_ - If your question is not addressed in the `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_\ , the `Discourse Forums <https://discourse.mozilla.org/c/deep-speech>`_ is the next place to look. They contain conversations on `General Topics <https://discourse.mozilla.org/t/general-topics/21075>`_\ , `Using Deep Speech <https://discourse.mozilla.org/t/using-deep-speech/21076/4>`_\ , and `Deep Speech Development <https://discourse.mozilla.org/t/deep-speech-development/21077>`_.
#. `Discourse Forums <https://discourse.mozilla.org/c/deep-speech>`_ - If your question is not addressed in the `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_\ , the `Discourse Forums <https://discourse.mozilla.org/c/deep-speech>`_ is the next place to look. They contain conversations on `General Topics <https://discourse.mozilla.org/t/general-topics/21075>`_\ , `Using Deep Speech <https://discourse.mozilla.org/t/using-deep-speech/21076/4>`_\ , and `Deep Speech Development <https://discourse.mozilla.org/t/deep-speech-development/21077>`_.

#.
`\ **Matrix chat** <https://chat.mozilla.org/#/room/#machinelearning:mozilla.org>`_ - If your question is not addressed by either the `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_ or `Discourse Forums <https://discourse.mozilla.org/c/deep-speech>`_\ , you can contact us on the ``#machinelearning`` channel on `Mozilla Matrix <https://chat.mozilla.org/#/room/#machinelearning:mozilla.org>`_\ ; people there can try to answer/help
#. `Matrix chat <https://chat.mozilla.org/#/room/#machinelearning:mozilla.org>`_ - If your question is not addressed by either the `FAQ <https://github.com/mozilla/DeepSpeech/wiki#frequently-asked-questions>`_ or `Discourse Forums <https://discourse.mozilla.org/c/deep-speech>`_\ , you can contact us on the ``#machinelearning`` channel on `Mozilla Matrix <https://chat.mozilla.org/#/room/#machinelearning:mozilla.org>`_\ ; people there can try to answer/help

#.
`\ **Issues** <https://github.com/mozilla/deepspeech/issues>`_ - Finally, if all else fails, you can open an issue in our repo.
#. `Issues <https://github.com/mozilla/deepspeech/issues>`_ - Finally, if all else fails, you can open an issue in our repo.
6 changes: 3 additions & 3 deletions doc/TRAINING.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ If you have a capable (NVIDIA, at least 8GB of VRAM) GPU, it is highly recommend
pip3 uninstall tensorflow
pip3 install 'tensorflow-gpu==1.15.2'
Please ensure you have the required `CUDA dependency <USING.rst#cuda-dependency>`_.
Please ensure you have the required :ref:`CUDA dependency <cuda-deps>`.

It has been reported for some people failure at training:

Expand All @@ -74,7 +74,7 @@ It has been reported for some people failure at training:
tensorflow.python.framework.errors_impl.UnknownError: Failed to get convolution algorithm. This is probably because cuDNN failed to initialize, so try looking to see if a warning log message was printed above.
[[{{node tower_0/conv1d/Conv2D}}]]
Setting the ``TF_FORCE_GPU_ALLOW_GROWTH`` environment variable to ``true`` seems to help in such cases. This could also be due to an incorrect version of libcudnn. Double check your versions with the `TensorFlow 1.15 documentation <USING.rst#cuda-dependency>`_.
Setting the ``TF_FORCE_GPU_ALLOW_GROWTH`` environment variable to ``true`` seems to help in such cases. This could also be due to an incorrect version of libcudnn. Double check your versions with the :ref:`TensorFlow 1.15 documentation <cuda-deps>`.

Common Voice training data
^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -179,7 +179,7 @@ Exporting a model for inference
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If the ``--export_dir`` parameter is provided, a model will have been exported to this directory during training.
Refer to the corresponding :github:`README.rst <native_client/README.rst>` for information on building and running a client that can use the exported model.
Refer to the :ref:`usage instructions <usage-docs>` for information on running a client that can use the exported model.

Exporting a model for TFLite
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down
11 changes: 8 additions & 3 deletions doc/USING.rst
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _usage-docs:

Using a Pre-trained Model
=========================

Expand All @@ -9,8 +11,9 @@ Inference using a DeepSpeech pre-trained model can be done with a client/languag
* `The Command-Line client <#using-the-command-line-client>`_
* :github:`The .NET client/language binding <native_client/dotnet/README.rst>`

Running ``deepspeech`` might, see below, require some runtime dependencies to be already installed on your system:
.. _runtime-deps:

Running ``deepspeech`` might, see below, require some runtime dependencies to be already installed on your system:

* ``sox`` - The Python and Node.JS clients use SoX to resample files to 16kHz.
* ``libgomp1`` - libsox (statically linked into the clients) depends on OpenMP. Some people have had to install this manually.
Expand All @@ -20,6 +23,8 @@ Running ``deepspeech`` might, see below, require some runtime dependencies to be

Please refer to your system's documentation on how to install these dependencies.

.. _cuda-deps:

CUDA dependency
^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -168,12 +173,12 @@ Note: the following command assumes you `downloaded the pre-trained model <#gett
./deepspeech --model deepspeech-0.7.0-models.pbmm --scorer deepspeech-0.7.0-models.scorer --audio audio_input.wav
See the help output with ``./deepspeech -h`` and the :github:`native client README <native_client/README.rst>` for more details.
See the help output with ``./deepspeech -h`` for more details.

Installing bindings from source
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If pre-built binaries aren't available for your system, you'll need to install them from scratch. Follow these :github:`native client installation instructions <native_client/README.rst>`.
If pre-built binaries aren't available for your system, you'll need to install them from scratch. Follow the :github:`native client build and installation instructions <native_client/README.rst>`.

Third party bindings
^^^^^^^^^^^^^^^^^^^^
Expand Down
46 changes: 46 additions & 0 deletions doc/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,52 @@
Welcome to DeepSpeech's documentation!
======================================

DeepSpeech is an open source Speech-To-Text engine, using a model trained by machine learning techniques based on `Baidu's Deep Speech research paper <https://arxiv.org/abs/1412.5567>`_. Project DeepSpeech uses Google's `TensorFlow <https://www.tensorflow.org/>`_ to make the implementation easier.

To install and use DeepSpeech all you have to do is:

.. code-block:: bash
# Create and activate a virtualenv
virtualenv -p python3 $HOME/tmp/deepspeech-venv/
source $HOME/tmp/deepspeech-venv/bin/activate
# Install DeepSpeech
pip3 install deepspeech
# Download pre-trained English model files
curl -LO https://github.com/mozilla/DeepSpeech/releases/download/v0.7.0/deepspeech-0.7.0-models.pbmm
curl -LO https://github.com/mozilla/DeepSpeech/releases/download/v0.7.0/deepspeech-0.7.0-models.scorer
# Download example audio files
curl -LO https://github.com/mozilla/DeepSpeech/releases/download/v0.7.0/audio-0.7.0.tar.gz
tar xvf audio-0.7.0.tar.gz
# Transcribe an audio file
deepspeech --model deepspeech-0.7.0-models.pbmm --scorer deepspeech-0.7.0-models.scorer --audio audio/2830-3980-0043.wav
A pre-trained English model is available for use and can be downloaded following the instructions in :ref:`the usage docs <usage-docs>`. For the latest release, including pre-trained models and checkpoints, `see the GitHub releases page <https://github.com/mozilla/DeepSpeech/releases/latest>`_.

Quicker inference can be performed using a supported NVIDIA GPU on Linux. See the `release notes <https://github.com/mozilla/DeepSpeech/releases/latest>`_ to find which GPUs are supported. To run ``deepspeech`` on a GPU, install the GPU specific package:

.. code-block:: bash
# Create and activate a virtualenv
virtualenv -p python3 $HOME/tmp/deepspeech-gpu-venv/
source $HOME/tmp/deepspeech-gpu-venv/bin/activate
# Install DeepSpeech CUDA enabled package
pip3 install deepspeech-gpu
# Transcribe an audio file.
deepspeech --model deepspeech-0.7.0-models.pbmm --scorer deepspeech-0.7.0-models.scorer --audio audio/2830-3980-0043.wav
Please ensure you have the required :ref:`CUDA dependencies <cuda-deps>`.

See the output of ``deepspeech -h`` for more information on the use of ``deepspeech``. (If you experience problems running ``deepspeech``, please check :ref:`required runtime dependencies <runtime-deps>`).

**Full documentation** available on `deepspeech.readthedocs.io <http://deepspeech.readthedocs.io/?badge=latest>`_.

.. toctree::
:maxdepth: 2
:caption: Introduction
Expand Down
2 changes: 1 addition & 1 deletion native_client/javascript/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Full project description and documentation on GitHub: [https://github.com/mozilla/DeepSpeech](https://github.com/mozilla/DeepSpeech).
Full project description and documentation on [https://deepspeech.readthedocs.io/](https://deepspeech.readthedocs.io/).

## Generating TypeScript Type Definitions

Expand Down
2 changes: 1 addition & 1 deletion native_client/python/README.rst
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
Full project description and documentation on GitHub: `https://github.com/mozilla/DeepSpeech <https://github.com/mozilla/DeepSpeech>`_
Full project description and documentation on `https://deepspeech.readthedocs.io/ <https://deepspeech.readthedocs.io/>`_

0 comments on commit 1acbed9

Please sign in to comment.