Link documentation to readthedocs (#31)

* update rtd yaml with instructions from rtd

* fix rtd badge on readme

* bump version for documation yaml

* Return to original readthedocs yaml

* update with explicit python version

* revert to rtd example

* package rtd with version

* return to working version

* remove commented code

* add basic documentation

* remove exploration notebook to dummy functions

* update dummy path

* remove dummy modules

* add links to README

.github/workflows/documentation.yml

@@ -16,10 +16,10 @@ jobs:
       fail-fast: false
     steps:
       - uses: actions/checkout@v2
-      - name: Set up Python 3.9
+      - name: Set up Python 3.11
         uses: actions/setup-python@v2
         with:
-          python-version: 3.9
+          python-version: 3.11
       - name: Python info
         shell: bash -l {0}
         run: |
@@ -30,7 +30,7 @@ jobs:
           python3 -m pip install --upgrade pip setuptools
           python3 -m pip install .[dev,publishing]
       - name: Install pandoc using apt
-        run: sudo apt install pandoc        
+        run: sudo apt install pandoc
       - name: Build documentation
         run: make coverage doctest html
         working-directory: docs

.readthedocs.yaml

@@ -1,4 +1,14 @@
+# .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-22.04
+  tools:
+    python: "3.11"
+
 python:
   install:
     - method: pip

README.md

@@ -13,7 +13,7 @@
 | **Other best practices**           |   |
 | Static analysis                    | [![workflow scq badge](https://sonarcloud.io/api/project_badges/measure?project=elpaco-escience_scikit-talk&metric=alert_status)](https://sonarcloud.io/dashboard?id=elpaco-escience_scikit-talk) |
 | Coverage                           | [![workflow scc badge](https://sonarcloud.io/api/project_badges/measure?project=elpaco-escience_scikit-talk&metric=coverage)](https://sonarcloud.io/dashboard?id=elpaco-escience_scikit-talk) |
-| Documentation                      | [![Documentation Status](https://readthedocs.org/projects/scikit-talk/badge/?version=latest)](https://scikit-talk.readthedocs.io/en/latest/?badge=latest) |
+| Documentation                      | [![Documentation Status](https://readthedocs.org/projects/sktalk/badge/?version=latest)](https://sktalk.readthedocs.io/en/latest/?badge=latest) |
 | **GitHub Actions**                 |   |
 | Build                              | [![build](https://github.com/elpaco-escience/scikit-talk/actions/workflows/build.yml/badge.svg)](https://github.com/elpaco-escience/scikit-talk/actions/workflows/build.yml) |
 | SonarCloud                         | [![sonarcloud](https://github.com/elpaco-escience/scikit-talk/actions/workflows/sonarcloud.yml/badge.svg)](https://github.com/elpaco-escience/scikit-talk/actions/workflows/sonarcloud.yml) |
@@ -40,7 +40,8 @@ python3 -m pip install .
 
 ## Documentation
 
-Include a link to your project's full documentation here.
+The user documentation can be found [here](https://sktalk.readthedocs.io/en/latest/?badge=latest).
+To read more about the aims of this software, [this paper](https://aclanthology.org/2021.sigdial-1.26/) by Liesenfeld _et al._ (2021) describes the project in detail.
 
 ## Contributing
 

docs/getting_started.rst

@@ -0,0 +1,30 @@
+.. _getting_started:
+
+Getting started
+---------------
+
+To get started with scikit-talk, you will need a transcription file.
+For example, you can download a file from the
+`Griffith Corpus of Spoken Australian English <https://ca.talkbank.org/data-orig/GCSAusE/>`_.
+
+Load a corpus using the parser for .cha files:
+
+.. code-block:: python
+
+    from sktalk.corpus.parsing.cha import ChaFile
+    parsed_cha = ChaFile('path/to/your/file.cha').parse()
+
+Access the metadata with:
+
+.. code-block:: python
+
+    parsed_cha.metadata
+
+Access the utterances with:
+
+.. code-block:: python
+
+    parsed_cha.utterances
+
+
+

docs/index.rst

@@ -3,16 +3,31 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to scikit-talk's documentation!
-==========================================================
+scikit-talk user documentation
+==============================
+
+Scikit-talk will be an open-source toolkit for processing collections of
+real-world conversational speech in Python. The toolkit aims to facilitate the
+exploration of large collections of transcriptions and annotations of
+conversational interaction, specifically tailored to applications in speech
+processing and Conversational AI.
+
+Scikit-talk is under active development, and currently includes a preprocessor
+module that allows the import of several common transcription formats.
+
+You can read the full paper here: `Liesenfeld et al. (2021) <https://aclanthology.org/2021.sigdial-1.26/>`_
 
 .. toctree::
-  :maxdepth: 2
-  :caption: Contents:
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   getting_started
+
 
-Indices and tables
-==================
+.. Indices and tables
+.. ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. .. * :ref:`genindex`
+.. .. * :ref:`modindex`
+.. * :ref:`search`

docs/installation.rst

@@ -0,0 +1,11 @@
+.. _installation:
+
+Installation
+------------
+
+The development version is available via GitHub. To install directly from
+GitHub, the following command can be used:
+
+::
+
+   pip install -U  git+https://github.com/elpaco-escience/scikit-talk.git