update 08.10

docs/source/getting_started.rst

@@ -58,7 +58,7 @@ Mac
 ```
 
 #. Ensure Java 11 is installed inside Anaconda distribution (``conda install -c anaconda openjdk``) if using Anaconda, or
-   via Homebrew otherwise (``brew cask install java``)
+   via Homebrew otherwise (``brew install openjdk``)
 #. Check Java version is 11 via ``java --version``
 #. Once PolyglotDB is installed, run :code:`pgdb install /path/to/where/you/want/data/to/be/stored`, or
    :code:`pgdb install` to save data in the default directory.

docs/source/index.rst

@@ -18,6 +18,7 @@ Contents:
    queries.rst
    developer.rst
    changelog.rst
+   troubleshooting.rst
 
 See `the PolyglotDB wiki`_ for the changelog.
 

docs/source/troubleshooting.rst

@@ -0,0 +1,19 @@
+.. _troubleshooting:
+
+***************
+Troubleshooting Tips
+***************
+
+This section contains several troubleshooting tips on installation, tutorials, etc. 
+
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   tshoot_install.rst 
+   tshoot_tut.rst
+   tshoot_other.rst
+
+

docs/source/tshoot_install.rst

@@ -0,0 +1,17 @@
+.. _tshoot_install:
+
+************
+Installation 
+************
+
+On Mac
+=============
+
+If the ``pgdb`` command does not work, you may try the following steps:
+
+1. Uninstall Java
+2. Make sure Anaconda is installed on your Mac. If you are using Miniconda, run ``miniconda install anaconda`` to install Anaconda. 
+3. Reinstall Java by ``conda install -anaconda openjdk``. Note that you should not use Homebrew to install Java, since Anaconda helps to manage the Java version appropriate for PolyGlot installation. 
+4. ``pgdb install``, ``pgdb start``, and ``pgdb stop`` should work now. 
+
+

docs/source/tshoot_other.rst

@@ -0,0 +1,33 @@
+.. _tshoot_other:
+
+************
+Others
+************
+
+Run time error 
+===============
+
+If this error occurs: 
+
+.. code-block:: python 
+
+    RuntimeError: 
+        An attempt has been made to start a new process before the
+        current process has finished its bootstrapping phase.
+
+        This probably means that you are not using fork to start your
+        child processes and you have forgotten to use the proper idiom
+        in the main module:
+
+            if __name__ == '__main__':
+                freeze_support()
+                ...
+
+        The "freeze_support()" line can be omitted if the program
+        is not going to be frozen to produce an executable.
+
+
+You need to add ``if __name__ == '__main__'`` at the beginning of your vowel-formant.py file.
+
+
+

docs/source/tshoot_tut.rst

@@ -0,0 +1,42 @@
+.. _tshoot_tut:
+
+************
+Tutorials
+************
+
+Corpus Structure
+===============
+
+* Your corpus should be arranged by speaker. 
+* Each speaker directory contains TextGrid files and the corresponding wav files. If some corresponding wav files are missing, the ``KeyError: 'vowel_file_path'`` may appear. 
+* If the KeyError still exists, you may reset the corpus as below. 
+
+.. code-block:: python 
+
+    with CorpusContext(corpus_name) as c:
+        c.reset()
+
+
+Defining Vowel Set (Tutorial 4)
+===============
+
+**In vowel formant analysis, make sure to check the output of the phone set, and accordingly define your own vowel set.** This is because, in Tutorial 4, the regex used to define the vowel set may not work for the language you are working on. 
+
+In other words, instead of using:
+
+.. code-block:: python
+
+    vowel_set = [re.search(vowel_regex, p).string for p in phone_set
+            if re.search(vowel_regex, p) != None and p not in non_speech_set]
+
+
+Use (e.g., for Cantonese): 
+
+.. code-block:: python 
+
+    vowel_set = ['6', '6j', '6w', '9', '9y', 'E:', 'O:', 'O:j', 'a:', 'a:j', 'a:w', 'ej', 'i:', 'ow', 'u:', 'y:']
+
+
+You can either use your own regex or type the vowels manually based the output of the phone set. 
+
+

rtd_requirements.txt

@@ -1,4 +1,4 @@
 sphinx
 numpydoc
 mock
-sphinx_rtd_theme
+sphinx_rtd_theme>=0.3.1