Merge pull request mozilla#2395 from lissyx/md-to-rst

Move from Markdown to reStructuredText

.cardboardlint.yml

@@ -1,2 +1,3 @@
 linters:
 - pylint:
+    filefilter: ['+ *.py', '+ bin/*.py']

CONTRIBUTING.rst

@@ -0,0 +1,53 @@
+Contribution guidelines
+=======================
+
+This repository is governed by Mozilla's code of conduct and etiquette guidelines. For more details, please read the `Mozilla Community Participation Guidelines <https://www.mozilla.org/about/governance/policies/participation/>`_.
+
+Before making a Pull Request, check your changes for basic mistakes and style problems by using a linter. We have cardboardlinter setup in this repository, so for example, if you've made some changes and would like to run the linter on just the changed code, you can use the follow command:
+
+.. code-block:: bash
+
+   pip install pylint cardboardlint
+   cardboardlinter --refspec master
+
+This will compare the code against master and run the linter on all the changes. We plan to introduce more linter checks (e.g. for C++) in the future. To run it automatically as a git pre-commit hook, do the following:
+
+.. code-block:: bash
+
+   cat <<\EOF > .git/hooks/pre-commit
+   #!/bin/bash
+   if [ ! -x "$(command -v cardboardlinter)" ]; then
+       exit 0
+   fi
+
+   # First, stash index and work dir, keeping only the
+   # to-be-committed changes in the working directory.
+   echo "Stashing working tree changes..." 1>&2
+   old_stash=$(git rev-parse -q --verify refs/stash)
+   git stash save -q --keep-index
+   new_stash=$(git rev-parse -q --verify refs/stash)
+
+   # If there were no changes (e.g., `--amend` or `--allow-empty`)
+   # then nothing was stashed, and we should skip everything,
+   # including the tests themselves.  (Presumably the tests passed
+   # on the previous commit, so there is no need to re-run them.)
+   if [ "$old_stash" = "$new_stash" ]; then
+       echo "No changes, skipping lint." 1>&2
+       exit 0
+   fi
+
+   # Run tests
+   cardboardlinter --refspec HEAD -n auto
+   status=$?
+
+   # Restore changes
+   echo "Restoring working tree changes..." 1>&2
+   git reset --hard -q && git stash apply --index -q && git stash drop -q
+
+   # Exit with status from test-run: nonzero prevents commit
+   exit $status
+   EOF
+   chmod +x .git/hooks/pre-commit
+
+This will run the linters on just the changes made in your commit.
+

README.rst

@@ -0,0 +1,91 @@
+Project DeepSpeech
+==================
+
+
+.. image:: https://readthedocs.org/projects/deepspeech/badge/?version=latest
+   :target: http://deepspeech.readthedocs.io/?badge=latest
+   :alt: Documentation
+
+
+.. image:: https://github.taskcluster.net/v1/repository/mozilla/DeepSpeech/master/badge.svg
+   :target: https://github.taskcluster.net/v1/repository/mozilla/DeepSpeech/master/latest
+   :alt: Task Status
+
+
+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 and extract
+   curl -LO https://github.com/mozilla/DeepSpeech/releases/download/v0.5.1/deepspeech-0.5.1-models.tar.gz
+   tar xvf deepspeech-0.5.1-models.tar.gz
+
+   # Download example audio files
+   curl -LO https://github.com/mozilla/DeepSpeech/releases/download/v0.5.1/audio-0.5.1.tar.gz
+   tar xvf audio-0.5.1.tar.gz
+
+   # Transcribe an audio file
+   deepspeech --model deepspeech-0.5.1-models/output_graph.pbmm --alphabet deepspeech-0.5.1-models/alphabet.txt --lm deepspeech-0.5.1-models/lm.binary --trie deepspeech-0.5.1-models/trie --audio audio/2830-3980-0043.wav
+
+A pre-trained English model is available for use and can be downloaded using `the instructions below <#using-a-pre-trained-model>`_. Currently, only 16-bit, 16 kHz, mono-channel WAVE audio files are supported in the Python client. 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.5.1-models/output_graph.pbmm --alphabet deepspeech-0.5.1-models/alphabet.txt --lm deepspeech-0.5.1-models/lm.binary --trie deepspeech-0.5.1-models/trie --audio audio/2830-3980-0043.wav
+
+Please ensure you have the required `CUDA dependencies <#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.md#required-dependencies>`_\ ).
+
+----
+
+**Table of Contents**
+
+
+* `Using a Pre-trained Model <USING.rst#using-a-pre-trained-model>`_
+
+  * `CUDA dependency <USING.rst#cuda-dependency>`_
+  * `Getting the pre-trained model <USING.rst#getting-the-pre-trained-model>`_
+  * `Model compatibility <USING.rst#model-compatibility>`_
+  * `Using the Python package <USING.rst#using-the-python-package>`_
+  * `Using the Node.JS package <USING.rst#using-the-nodejs-package>`_
+  * `Using the Command Line client <USING.rst#using-the-command-line-client>`_
+  * `Installing bindings from source <USING.rst#installing-bindings-from-source>`_
+  * `Third party bindings <USING.rst#third-party-bindings>`_
+
+* `Training your own Model <TRAINING.rst#training-your-own-model>`_
+
+  * `Prerequisites for training a model <TRAINING.rst#prerequisites-for-training-a-model>`_
+  * `Getting the training code <TRAINING.rst#getting-the-training-code>`_
+  * `Installing Python dependencies <TRAINING.rst#installing-python-dependencies>`_
+  * `Recommendations <TRAINING.rst#recommendations>`_
+  * `Common Voice training data <TRAINING.rst#common-voice-training-data>`_
+  * `Training a model <TRAINING.rst#training-a-model>`_
+  * `Checkpointing <TRAINING.rst#checkpointing>`_
+  * `Exporting a model for inference <TRAINING.rst#exporting-a-model-for-inference>`_
+  * `Exporting a model for TFLite <TRAINING.rst#exporting-a-model-for-tflite>`_
+  * `Making a mmap-able model for inference <TRAINING.rst#making-a-mmap-able-model-for-inference>`_
+  * `Continuing training from a release model <TRAINING.rst#continuing-training-from-a-release-model>`_
+  * `Training with Augmentation <TRAINING.rst#training-with-augmentation>`_
+
+* `Contribution guidelines <CONTRIBUTING.rst>`_
+* `Contact/Getting Help <SUPPORT.rst>`_

RELEASE.rst

@@ -0,0 +1,12 @@
+
+Making a (new) release of the codebase
+======================================
+
+
+* Update version in VERSION file, commit
+* Open PR, ensure all tests are passing properly
+* Merge the PR
+* Fetch the new master, tag it with (hopefully) the same version as in VERSION
+* Push that to Github
+* New build should be triggered and new packages should be made
+* TaskCluster should schedule a merge build **including** a "DeepSpeech Packages" task

SUPPORT.rst

@@ -0,0 +1,17 @@
+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.
+
+#. 
+   `\ **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>`_.
+
+#. 
+   `\ **IRC** <https://wiki.mozilla.org/IRC>`_ - 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 IRC <https://wiki.mozilla.org/IRC>`_\ ; 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.