Feature/61/demo (#62)

* Added demo doc and resources

* Incorporated JPE's feedback

* Update DEMO.rst

* Updated demo

* Moved files

* Update DEMO_2.rst

* Update DEMO_2.rst

* Update DEMO_2.rst

* Update DEMO_2.rst

* Update DEMO_2.rst

Todo: named arguments, check RST rendering

* Update DEMO_2.rst

* Update DEMO_2.rst

* Update DEMO_2.rst

* Update DEMO_2.rst

* Update DEMO_2.rst

* Update DEMO_2.rst

* Update DEMO_2.rst

* Changed file name to tutorial

Plus other fixes

* remove tests/BDD/features/normalization_file_handling.feature from .gitignore

* proper restructuredtext + indentation, etc

* Removed duplicate file and edits

* Update tutorial.rst

* Update tutorial.rst

* add unit test, make error of file parsing more readable

* Make opcode counts output (`--diffcounts`) more palatable in markdown and rst, some changes to tutorial...

* add results for kaldi

* add example cli output for worddiffs

* bump version

* Show inline terminal output in tutorial instead of image, add output for 2nd benchmark, add restructuredtext diff dialect, add css for terminal output

* put all output in terminal container + lineblock

* only build html for readthedocs

* Add required version

* documentatio config: use html_css_files

* css file relative to static path

* proper readthedocs conf

* fancier terminal screens

* improve terminal output: break on any char, remove unnecessary zerowidthspaces

* final tutorial cleanup, add output for wer results, improve XML regex (to avoid eg. " is 5 < 6, or is 5 > 6" to filter out "< 6, or is 5 >")

* use simpler rst notation for code blocks and inline code

* use \\1e instead of r'\1e' (better for documentation)

* Proper :param: doctags, use rtype or inline type definition in future

* Further using the more readable :: syntax for code-blocks

* add_zero_width_space not used, set default sphinx highlight language to none

* remove hard-wrap op text

Author: EyalLavi

.gitignore

@@ -39,4 +39,3 @@ venv/
 ENV/
 env.bak/
 venv.bak/
-

.readthedocs.yml

@@ -1,4 +1,10 @@
+version: 2
+
 python:
   version: 3.7
   install:
     - requirements: docs/requirements.txt
+
+formats:
+  - htmlzip
+  - epub

README.rst

@@ -18,7 +18,7 @@ Benchmarking STT
     :alt: Documentation Status
 
 .. image:: docs/img/benchmarksttcli.png
-
+    :alt: Example command line output
 
 About
 ------
@@ -31,26 +31,20 @@ Because of the wide range of languages, algorithms and audio characteristics, no
 
 
 
-Usage
-------
-
-.. code-block:: bash
-
-    $ benchmarkstt --reference reference.txt --hypothesis hypothesis.txt --diffcounts
-
-Return the number of word insertions, deletions, replacements and matches for the hypothesis transcript compared to the reference. 
+Usage examples
+--------------
 
-.. code-block:: bash
+Returns the number of word insertions, deletions, replacements and matches for the hypothesis transcript compared to the reference::
 
-    $ benchmarkstt -r reference.txt -h hypothesis.txt --wer --lowercase
+    benchmarkstt --reference reference.txt --hypothesis hypothesis.txt --diffcounts
 
-Return the Word Error Rate after lowercasing both reference and hypothesis. This normlization improves the accuracy of the Word Error Rate as it removes diffs that might otherwise be considered errors.
+Returns the Word Error Rate after lowercasing both reference and hypothesis. This normlization improves the accuracy of the Word Error Rate as it removes diffs that might otherwise be considered errors::
 
-.. code-block:: bash
+    benchmarkstt -r reference.txt -h hypothesis.txt --wer --lowercase
 
-    $ benchmarkstt -r reference.txt -h hypothesis.txt --worddiffs --config conf
+Returns a visual diff after applying all the normalization rules specified in the config file::
 
-Return a visual diff after applying all the normalization rules specified in the config file.
+    benchmarkstt -r reference.txt -h hypothesis.txt --worddiffs --config conf
 
 
 Further information

VERSION

@@ -1 +1 @@
-1.0rc5
+1.0rc6

docs/CODE_OF_CONDUCT.rst

@@ -1,7 +1,7 @@
 Code of Conduct
 ===============
 
-:code:`Status: Draft`
+``Status: Draft``
 
 We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristic.
 

docs/CONTRIBUTING.rst

@@ -1,7 +1,7 @@
 Contributing
 ------------
 
-:code:`[Status: Draft]`
+``[Status: Draft]``
 
 This project has a :doc:`CODE_OF_CONDUCT` that we expect all of our contributors to abide by, please check it out before contributing.
 
@@ -10,11 +10,11 @@ Pull requests and branching
 
 - Before working on a feature *always* create a new branch first. (or fork the project).
 - Branches should be short lived, except branches specifically labelled 'experiment'.
-- Once work is complete push the branch up on to GitHub for review. Make sure your branch is up to date with :code:`master` before making a pull request.
-  Eg. use :code:`git merge origin/master`
-- Once a branch has been merged into :code:`master`, delete it.
+- Once work is complete push the branch up on to GitHub for review. Make sure your branch is up to date with ``master`` before making a pull request.
+  Eg. use ``git merge origin/master``
+- Once a branch has been merged into ``master``, delete it.
 
-:code:`master` is rarely committed to directly unless the change is quite trivial or a code review is unnecessary (code formatting or documentation updates for example).
+``master`` is rarely committed to directly unless the change is quite trivial or a code review is unnecessary (code formatting or documentation updates for example).
 
 
 .. Good example of contribution guideline

docs/INSTALL.rst

@@ -18,27 +18,23 @@ This is the easiest and preferred way of installing ``benchmarkstt``.
     - `Installing Python 3 on Windows <https://docs.python-guide.org/starting/install3/win/>`_
     - `Installing Python 3 on Linux <https://docs.python-guide.org/starting/install3/linux/>`_
 
-2. Install the package using :code:`pip`, this will also install all requirements
-
-   .. code-block:: bash
+2. Install the package using ``pip``, this will also install all requirements::
 
       pip install benchmarkstt
 
 3. Test and use
 
    BenchmarkSTT should now be installed and usable.
 
-   .. parsed-literal::
+   .. container:: terminal
 
-      $ benchmarkstt --version
-      benchmarkstt: |release|
-      $ echo IT WORKS! | benchmarkstt-tools normalization --lowercase
-      it works!
+      | $> benchmarkstt --version
+      | benchmarkstt: |release|
+      | $> echo IT WORKS! | benchmarkstt-tools normalization --lowercase
+      | it works!
 
 
-   Use the :code:`--help` option to get all available options.
-
-   .. code-block:: bash
+   Use the ``--help`` option to get all available options::
 
       benchmarkstt --help
       benchmarkstt-tools normalization --help