From 1ae90b90a1ae8343f70d80d29eafc3f6d0f55b54 Mon Sep 17 00:00:00 2001
From: Stefan Sullivan <stefan.sullivan@gmail.com>
Date: Tue, 10 Dec 2024 21:18:50 -0800
Subject: [PATCH] add documentation for invoking mirdata as a script

---
 README.md                |  6 ++++
 docs/source/tutorial.rst | 72 ++++++++++++++++++++++++++++++++++++----
 2 files changed, 72 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 1643a73ae..821f4c820 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,12 @@ orchset.validate()  # validate that all the expected files are there
 example_track = orchset.choice_track()  # choose a random example track
 print(example_track)  # see the available data
 ```
+
+Or using the CLI:
+```bash
+python -m mirdata orchset  # download and validate the dataset
+```
+
 See the [documentation](https://mirdata.readthedocs.io/) for more examples and the API reference.
 
 
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
index bd251b047..2209bddc8 100644
--- a/docs/source/tutorial.rst
+++ b/docs/source/tutorial.rst
@@ -9,12 +9,74 @@ Installation
 
 To install Mirdata:
 
-    .. code-block:: console
+.. code-block:: console
 
-        pip install mirdata
+    pip install mirdata
 
 We recommend to do this inside a conda or virtual environment for reproducibility.
 
+Command-Line Interface
+----------------------
+
+To get started with mirdata, execute the following in your console:
+
+.. code-block:: console
+
+    python -m mirdata --help
+
+Print a list of all available dataset loaders by calling:
+
+.. code-block:: console
+
+    python -m mirdata --list
+    python -m mirdata -l
+    python -m mirdate  # If you don't specify a dataset, it defaults to listing datasets
+
+Download one or more datasets by specifying their name as arguments
+
+.. code-block:: console
+
+    python -m mirdata orchset maestro
+
+You can specify which version of a dataset you'd like to download with `--version`
+
+.. code-block:: console
+
+    python -m mirdata maestro --version=2.0.0
+    python -m mirdata maestro -v 2.0.0
+
+mirdata will choose a default location for all MIR datasets. If you'd like to redirect the download destination, you
+can do the following
+
+.. code-block:: console
+
+    python -m mirdata maestro --output /opt/data/mir/maestro
+
+By default mirdata will validate any downloaded dataset(s). If you want to skip validation you can use `--no-validate`
+
+.. code-block:: console
+
+    python -m mirdata maestro --no-validate
+
+Or you can print just citations or licenses with `--citation` and `--license`.
+
+.. code-block:: console
+
+    python -m mirdata maestro --citation --license
+    python -m mirdata maestro -c -L  #equivalent to above
+
+When you ask for either a license or a citation, mirdata will not download/validate the dataset. If you want to
+download _and_ print a license or citation, you can add the --download flag
+
+.. code-block:: console
+
+    python -m mirdata maestro --citation --download
+    python -m mirdata maestro -cd
+
+
+Initializing a dataset
+^^^^^^^^^^^^^^^^^^^^^^
+
 Mirdata is easily imported into your Python code by:
 
 .. code-block:: python
@@ -22,8 +84,6 @@ Mirdata is easily imported into your Python code by:
     import mirdata
 
 
-Initializing a dataset
-^^^^^^^^^^^^^^^^^^^^^^
 
 Print a list of all available dataset loaders by calling:
 
@@ -37,7 +97,7 @@ To use a loader, (for example, ``orchset`) you need to initialize it by calling:
 .. code-block:: python
 
     import mirdata
-    orchset = mirdata.initialize('orchset', data_home='/choose/where/data/live')
+    orchset = mirdata.initialize('orchset', data_home='/choose/where/data/lives')
 
 Now ``orchset`` is a ``Dataset`` object containing common methods, described below.
 
@@ -50,7 +110,7 @@ Use ``version`` parameter if you wish to use a version other than the default on
 .. code-block:: python
 
     import mirdata
-    dataset = mirdata.initialize('orchset', data_home='/choose/where/data/live', version="1.0")
+    dataset = mirdata.initialize('orchset', data_home='/choose/where/data/lives', version="1.0")
 
 
 Downloading a dataset