Merge pull request #275 from jwjacobson/dev

Dev

docs/about/appfocus.rst

@@ -0,0 +1,4 @@
+App focus, or what jazztunes is *not*
+======================================
+
+Inspired by the Unix philosophy of "do one thing and do it well", the focus of this app is repertoire management. It is not a general practice app, and it is not a tune *learning* app. There are other resources that fulfill those functions. Jazztunes assumes the user has access to the materials they need to learn a tune (recordings, sheet music, etc.) outside of the app itself. What it offers is easy and intuitive access to all tunes known by the user, filtered and sorted by any desired criteria.

docs/about/future.rst

@@ -0,0 +1,14 @@
+Planned features
+=================
+
+There are two major features still to be implemented:
+
+Custom tags
+------------
+
+The user can add any tag to they want to any tune, e.g. "ballad".
+
+Tune analytics
+---------------
+
+Track all plays of a given tune, allowing the user to see what tunes they play most and least often.

docs/about/index.rst

@@ -0,0 +1,11 @@
+About jazztunes
+================
+
+Here you'll find information about the origin and goals of jazztunes.
+
+.. toctree::
+   :maxdepth: 2
+
+   whyjazztunes
+   appfocus
+   future

docs/about/whyjazztunes.rst

@@ -0,0 +1,8 @@
+Why jazztunes?
+===============
+
+An important part of learning to play jazz is memorizing tunes, usually taken from the canon of `jazz <https://en.wikipedia.org/wiki/List_of_jazz_standards>`_ and `popular <https://en.wikipedia.org/wiki/Great_American_Songbook>`_ standard songs. These can number less than 10 for the beginning student, up to 100 or more for more advanced students, to hundreds or even over a thousand for professionals. Shared knowledge of a common set of tunes allows jazz musicians to successfully make music together with little to no preparation and is a distinctive feature of the artform.
+
+My own experience learning to play jazz has included a fair amount of frustration in trying to grow my repertoire. Tunes have to be regularly integrated into practice so that they enter long-term memory. This isn't difficult when one only knows a few tunes, but as my own repertoire approached the 100-tune threshold, I had difficulty keeping them all straight, and it often felt that for every new tune I learned, another one would slip out of the rotation and be forgotten, necessitating tiresome relearning. I have talked to enough other players to know that this issue is not unique to me; it is a general problem for jazz musicians, at least at the student and amateur level.
+
+Jazztunes helps to solve this problem by allowing you keep track of all the tunes you know, search and sort them by various criteria, and, crucially, see when you last played a tune, so you know which ones you need to revisit.

docs/conf.py

@@ -22,5 +22,13 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "alabaster"
+html_theme = "classic"
 html_static_path = ["_static"]
+
+
+html_sidebars = {
+    "**": [
+        "globaltoc.html",  # Table of contents
+        "searchbox.html",  # Search box
+    ],
+}

docs/index.rst

@@ -3,18 +3,27 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to jazztunes's documentation!
+Jazztunes user manual
 =====================================
+**Jazztunes** is a jazz repertoire management app.
+
+You can use it for free at `jazztunes.org <https://jazztunes.org>`_.
+
+The source code is available on `Github <https://github.com/jwjacobson/jazztunes>`_.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+
+   about/index
+   using/index
+
+
 
 
 
-Indices and tables
-==================
+.. Indices and tables
+.. ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. * :ref:`genindex`
+.. * :ref:`modindex`
+.. * :ref:`search`

docs/using/adding.rst

@@ -0,0 +1,12 @@
+Adding tunes
+===============
+There are two ways to add tunes to your repertoire: creating them manually or taking them from the public repertoire.
+
+Creating tunes manually
+-----------------------
+To create a tune, click the **create** button on the navbar. The only required field is "title."
+
+Taking tunes
+-------------
+The public repertoire contains 200 common tunes. Access it by clicking the **public** button on the navbar.
+To add a tune, click the **take** button. the tune will immediately enter your repertoire, and you will have the option of setting when you last played the tune and your knowledge of it. 

docs/using/index.rst

@@ -0,0 +1,11 @@
+Using jazztunes
+================
+To start using jazztunes, first create an account at `jazztunes.org <https://jazztunes.org>`_.
+
+.. toctree::
+   :maxdepth: 2
+
+   adding
+   managing
+   playing
+   searching

docs/using/managing.rst

@@ -0,0 +1,7 @@
+Managing tunes
+==============
+Managing tunes is done from the **home** page, accessed by clicking **jazztunes** on the left side of the navbar.
+
+Press the edit button to edit a tune and the delete button to delete it.
+
+You can also sort tunes by column by clicking the column name. Use shift-click to sort by multiple columns.

docs/using/playing.rst

@@ -0,0 +1,11 @@
+Playing tunes
+=============
+
+You can 'play' tunes by clicking the **play** button on the homepage, or by using the **Play** page, accessed from the navbar.
+
+The **Play** page will recommend a tune to play based on your search results (see XX for more on searching). If you submit an empty search if will use your whole repertoire.
+
+Regularly updating your plays is the most useful feature of the app!
+
+
+

docs/using/searching.rst

@@ -0,0 +1,14 @@
+Searching your repertoire
+=========================
+
+The **Home**, **Play**, and **Public** pages all contain a search box that uses the same logic.
+
+By default, every field is searched for your search term. If you enter multiple terms, the search uses AND logic. For example, if you search **monk** you will see all tunes with monk in any fields (usually composer). If you search **monk bud**, it will only return "In Walked Bud" (assuming it's in your repertoire).
+
+Jazz composer names have built-in substitutions using their nicknames or first names, so searching **miles** will return Miles Davis tunes, **bird** will return Charlie Parker tunes, etc.
+
+Use a **-** before a term to exclude it from the search results.
+
+You can also use the format **field:term** to search a specific field. Currently supported fields are **title**, **composer**, **key** (the key column, a tune's main key), **keys** (both the Key and Other Keys columns), **form**, **style**, **meter**, and **year**. It is most useful for key, keys, and form.
+
+The **haven't played in** dropdown lets you filter by how long it's been since you've played a tune. This allows you to easily target tunes at the highest risk of being forgotten.

tests/conftest.py

@@ -10,7 +10,7 @@
 @pytest.fixture()
 def tune_set(db, client):
     """
-    Create a tune set for use in tests that require one.
+    Create a tune set for use in query tests.
     """
     tunes = {
         Tune.objects.create(

tune/templates/tune/list.html

@@ -18,7 +18,7 @@ <h5 class="card-title">Tune Search</h5>
                 <form method="post" action="{% url 'tune:tune_list' %}">
                     {% csrf_token %}
                     <label for="basic_search"></label>
-                    <input id="search_term" type="text" name="search_term" class="ms-0 ps-0">
+                    <input id="search_term" type="text" name="search_term" value="{{ search_term_string }}" class="ms-0 ps-0">
             </div>
         <div class="col-12 my-2">
         <label for="timespan">Haven't played in:</label>

tune/views.py

@@ -155,18 +155,25 @@ def tune_list(request):
         search_form = SearchForm(request.POST)
         if search_form.is_valid():
             search_terms = search_form.cleaned_data["search_term"].split(" ")
+            search_term_string = " ".join(search_terms)
             timespan = search_form.cleaned_data["timespan"]
             results = return_search_results(request, search_terms, tunes, search_form, timespan)
             tunes = results.get("tunes")
             tune_count = results.get("tune_count", 0)
     else:
         search_form = SearchForm()
+        search_term_string = " "
 
     request.session["tune_count"] = tune_count
     return render(
         request,
         "tune/list.html",
-        {"tunes": tunes, "search_form": search_form, "tune_count": tune_count},
+        {
+            "tunes": tunes,
+            "search_form": search_form,
+            "tune_count": tune_count,
+            "search_term_string": search_term_string,
+        },
     )