Merge pull request #153 from NickleDave/convert-docs-myst

Convert docs to markdown + use myst parser, fix #151

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-20.04
+  apt_packages:
+    - libsndfile1
+  tools:
+    python: "3.8"
+
+sphinx:
+   configuration: doc/conf.py
+
+python:
+   install:
+     - method: pip
+       path: .
+       extra_requirements:
+        - doc

doc/background.rst → doc/background.md

@@ -1,13 +1,10 @@
-.. _background:
+(background)=
 
-==============
-**Background**
-==============
+# **Background**
 
-**Why is** ``crowsetta`` **needed**?
-====================================
+## **Why is** `crowsetta` **needed**?
 
-The target audience of ``crowsetta`` is anyone that works with birdsong
+The target audience of `crowsetta` is anyone that works with birdsong
 or any other vocalization that is annotated in some way, meaning someone took the time to
 figure out where elements of the vocalizations start and stop, and has assigned labels to those
 elements. Maybe you are a neuroscientist trying to figure out how songbirds learn their song,
@@ -19,55 +16,55 @@ Alzheimer's disease, etc., etc., ...
 To run a computational analysis on this kind of data, you'll need to get the annotation
 out of a file, which often means you'll end up writing something like this:
 
-.. code-block:: python
-
-    from scipy.io import loadmat  # function from scipy library for loading Matlab data files
-    annot = loadmat('bird1_experiment1_annotation_2018-11-17_083521.mat', squeeze_me=True)
-    onsets = annot['onsets']  # unpack from dictionary
-    onsets = np.asarray(onsets)  # convert to an array
-    onsets = onsets / 1000  # convert from milliseconds to seconds
+```python
+from scipy.io import loadmat  # function from scipy library for loading Matlab data files
+annot = loadmat('bird1_experiment1_annotation_2018-11-17_083521.mat', squeeze_me=True)
+onsets = annot['onsets']  # unpack from dictionary
+onsets = np.asarray(onsets)  # convert to an array
+onsets = onsets / 1000  # convert from milliseconds to seconds
+```
 
 This is verbose and not easy to read. You could do some of it in one line ...
 
-.. code-block:: python
-
-    onsets = np.asarray(annot['onsets']) / 1000
+```python
+onsets = np.asarray(annot['onsets']) / 1000
+```
 
 ... but now the next time you read that one-liner, you will have to mentally unpack it.
 
-Such code quickly turns into `boilerplate <https://en.wikipedia.org/wiki/Boilerplate_code>`_
+Such code quickly turns into [boilerplate](https://en.wikipedia.org/wiki/Boilerplate_code)
 that you will write any time you need to work with this data. It becomes repetitive and
-presents many opportunities for easy-to-miss bugs (e.g. a line with a variable named ``offset``
-where you meant to type ``onset`` of some syllable or phoneme or whatever, because you cut and
-pasted the line above it, and forgot to change ``off`` to ``on``\ ).
+presents many opportunities for easy-to-miss bugs (e.g. a line with a variable named `offset`
+where you meant to type `onset` of some syllable or phoneme or whatever, because you cut and
+pasted the line above it, and forgot to change `off` to `on`).
 
 And things can become even more complicated if you have to deal with annotation stored
 in other formats, such as a database. Here's an example of one way
 
-.. code-block:: python
-
-    import pymyseql
+```python
+import pymyseql
+```
 
 What would be nice is to have data types that represent annotation in a concise way, and
 that we can manipulate like we would some native Python data type like a list or a
-dictionary. ``crowsetta`` provides such data types: ``Sequence``\ s and ``Segment``\ s.
+dictionary. `crowsetta` provides such data types: `Sequence`s and `Segment`s.
 
-**How** ``crowsetta`` **works**
-===============================
+## **How** `crowsetta` **works**
 
-Internally, ``crowsetta`` takes whatever format you give it for a pile of files,
-and turns that into a bunch of ``Sequence``\ s made up of ``Segment``\ s. For someone working
-with birdsong, the ``Sequence``\ s will be single audio files / song bouts, and the
-``Segment``\ s will be syllables in those song bouts (99.9% of the time). Then, if
-you need it to, ``crowsetta`` can spit out your ``Sequence``\ s of ``Segment``\ s in
+Internally, `crowsetta` takes whatever format you give it for a pile of files,
+and turns that into a bunch of `Sequence`s made up of `Segment`s. For someone working
+with birdsong, the `Sequence`s will be single audio files / song bouts, and the
+`Segment`s will be syllables in those song bouts (99.9% of the time). Then, if
+you need it to, `crowsetta` can spit out your `Sequence`s of `Segment`s in
 a simple text file with a comma-separated value (csv) format. This file format
 was chosen because it is widely considered to be the most robust way to share data.
 
 An example csv looks like this:
 
-.. literalinclude:: ../tests/test_data/csv/gy6or6_032312.csv
-   :lines: 1-5
-   :language: none
+```{literalinclude} ../tests/test_data/csv/gy6or6_032312.csv
+:language: none
+:lines: 1-5
+```
 
-Now that you have that, you can load it into a `pandas` dataframe or an Excel 
+Now that you have that, you can load it into a `pandas` dataframe or an Excel
 spreadsheet or a SQL database, or whatever you want.

doc/conf.py

@@ -39,12 +39,16 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'myst_parser',
     'sphinx.ext.autodoc',
+    'sphinx.ext.coverage',
+    'sphinx_copybutton',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
-    'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon',
+    'sphinxext.opengraph',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
 ]