Merge pull request #98 from ReadAlongs/master

Release the latest features of Studio

.pylintrc

@@ -0,0 +1,7 @@
+[MASTER]
+# A lot of test cases depend on etree, let's allow pylint to load it
+extension-pkg-allow-list=lxml.etree
+# We use isort for sorting our imports, so nevermind what pylint thinks
+disable=wrong-import-order
+# Add . to the PYTHONPATH so pylint knows test cases can import basic_test_case
+init-hook="import sys; sys.path.append('.')"

.travis.yml

@@ -1,5 +1,5 @@
 sudo: required
-dist: xenial
+dist: bionic
 
 language: python
 python:

README.md

@@ -7,8 +7,6 @@
 [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/ReadAlongs/Studio)
 [![Documentation Status](https://readthedocs.org/projects/readalong-studio/badge/)](https://readalong-studio.readthedocs.io)
 
-:warning: :construction: This repo is currently **under construction** and is not stable. :construction: :warning:
-
 > Audiobook alignment for Indigenous languages!
 
 This library is an end-to-end audio/text aligner. It is meant to be used together with the [ReadAlong-Web-Component](https://github.com/roedoejet/ReadAlong-Web-Component) to interactively visualize the alignment.
@@ -19,9 +17,12 @@ This library is an end-to-end audio/text aligner. It is meant to be used togethe
   - [Table of Contents](#table-of-contents)
   - [Background](#background)
   - [Install](#install)
+    - [Dependencies](#installing-dependencies)
+    - [Studio itself](#Installing-ReadAlongs-Studio-itself)
+    - [Validation](#Verifying-your-installation)
   - [Usage](#usage)
     - [CLI](#cli)
-    - [Studio](#studio)
+    - [Studio](#Studio-web-application)
     - [Docker](#docker)
   - [Maintainers](#maintainers)
   - [Contributing](#contributing)
@@ -42,8 +43,7 @@ i.e. a package of:
 
 Which can be loaded using the read-along [web component](https://github.com/roedoejet/ReadAlong-Web-Component). See also [Studio Output Realizations](https://readalong-studio.readthedocs.io/en/latest/outputs.html).
 
-Optionally a book can be generated as a standalone HTML page or
-as an ePub file.
+Optionally a book can be generated as a standalone HTML page, XHTML, Praat TextGrid, ELAN Eaf file, as well as WebVTT or SRT subitle formats.
 
 1. (optional) Pre-segment inputs, consisting of:
    - Single audio file
@@ -57,10 +57,62 @@ as an ePub file.
 
 ## Install
 
-You will need: **Python 3.7 or higher**.
+### Installing dependencies
+
+Before you can install the ReadAlong Studio, you will need to install these dependencies:
+
+ - Python, version 3.7 or higher,
+ - [FFmpeg](https://ffmpeg.org/),
+ - a C compiler,
+ - Git (optional, needed to get the current development version).
+
+#### Dependencies on MacOS
+
+First install Homebrew, then use it to install FFmpeg with `brew install ffmpeg`.
+
+The compiler should already be on your machine.
+
+Consider Xcode for your XML and text file editor.
+
+#### Dependencies on Linux
+
+If FFmpeg is not already installed, `<your package manager> install ffmpeg` should add it.
+
+The compiler should already be there, but run `<your package manager> install gcc` if not.
+
+#### Dependencies on Windows
+
+##### The easy way, using Anaconda
+
+Anaconda/Miniconda will install Python 3 and the required compiler automatically for you,
+and simplifies ffmpeg and git installation. We recommend this solution.
 
-To install the latest version published to PyPI, you can run a standard pip
-installation: `pip install readalongs`. Be warned, however, that this project is currectly very active so the published version could be out-of-date. Consider installing the current development version instead.
+Download and install the latest "Miniconda3 Windows 64-bit" installer from
+https://docs.conda.io/en/latest/miniconda.html.
+You can accept all the default options suggested by the installer.
+
+Launch an Anaconda Prompt (this should be available from your Start menu after
+installation) and run:
+
+    conda install ffmpeg
+    conda install git
+
+You can then run the pip install and git commands below, and use readalongs, all from the Anaconda
+Prompt.
+
+##### The hard way
+
+If you know what you're doing, you can install the dependencies directly on your machine:
+
+ - Install Python3 for Windows.
+ - Install [FFmpeg builds for Windows](https://ffmpeg.zeranoe.com/builds/) ([alternative instructions](https://windowsloop.com/install-ffmpeg-windows-10/)).
+ - Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017) (search for "Build Tools", select C++ when prompted).
+ - Install Git for Windows (optional).
+
+### Installing ReadAlongs Studio itself
+
+To install the latest version of readalongs published to PyPI, you can run a standard pip
+installation: `pip install readalongs`. Be warned, however, that this project is still very active so the published version could be out-of-date. Consider installing the current development version instead.
 
 To install the current development version, clone the repo and pip install it
 locally:
@@ -71,13 +123,17 @@ $ cd Studio
 $ pip install -e .
 ```
 
-If you don't already have it, you will also need [FFmpeg](https://ffmpeg.org/).
+### Verifying your installation
+
+Run `readalongs -h` to confirm that installation was successful.
+
+If you installed the current development version with Git, you can also run the full test suite:
 
-- Windows: [FFmpeg builds for Windows](https://ffmpeg.zeranoe.com/builds/) ([helpful instructions](https://windowsloop.com/install-ffmpeg-windows-10/))
-- Mac: `brew install ffmpeg`
-- Linux: `<your package manager> install ffmpeg`
+    cd Studio/test
+    python run.py dev
 
-On Windows, you might also need [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017) (search for "Build Tools", select C++ when prompted).
+And you can download our [open samples on GitHub](https://github.com/ReadAlongs/OpenSamples)
+to run your first alignments.
 
 ## Usage
 
@@ -98,13 +154,6 @@ Basic alignment is done with the following command.
 
 `readalongs align TEXTFILE WAVFILE OUTPUTNAME`
 
-#### ePub
-
-In order to generate an ePub, there are two steps:
-
-1. `readalongs align --output-xhtml TEXTFILE WAVFILE OUTPUTNAME`
-2. `readalongs epub OUTPUTNAME.smil OUTPUTNAME.epub`
-
 ### Studio web application
 
 ReadAlong-Studio has a web interface for creating interactive audiobooks. The web app can be served by first installing ReadAlong-Studio and then running `readalongs run`. A web app will then be available on port 5000.

docs/README.md

@@ -0,0 +1,32 @@
+# Contributing to the documentation
+
+## Edit the files
+
+To contribute to the ReadAlongs Studio documentation, edit the `.rst` files in
+this folder.
+
+## Build the documentation locally
+
+To build the documention for local inspection, run one of these commands,
+which will build the documentation in `./_build/html/` or
+`./_build/singlehtml/`:
+
+    make html  # multi-page HTML site
+    make singlehtml  # single-page HTML document
+
+## View the documentation locally
+
+To view the documentation, run an HTTP server in the directory where the build
+is found, e.g.,
+
+    cd _build/html
+    python3 -m http.server
+
+and navigate to http://127.0.0.1:8000 to view the results (or whatever port
+your local web server displays).
+
+## Publish the changes
+
+Once your changes are pushed to GitHub and merged into `master` via a Pull
+Request, the documentation will be automatically built and published to
+https://readalong-studio.readthedocs.io/en/latest/