From 65d888e871a465759d620c591a8528a8e848e600 Mon Sep 17 00:00:00 2001 From: JW Jacobson <116485484+jwjacobson@users.noreply.github.com> Date: Sun, 16 Jun 2024 12:58:53 -0400 Subject: [PATCH 1/2] Make search terms persist after search in list template --- tune/templates/tune/list.html | 2 +- tune/views.py | 9 ++++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/tune/templates/tune/list.html b/tune/templates/tune/list.html index 7b6dfe9..afbdc1f 100644 --- a/tune/templates/tune/list.html +++ b/tune/templates/tune/list.html @@ -18,7 +18,7 @@
Tune Search
{% csrf_token %} - +
diff --git a/tune/views.py b/tune/views.py index b8979e0..9da253b 100644 --- a/tune/views.py +++ b/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, + }, ) From 6dccc9544f1b7004a90c04328ee4e937afa79ee1 Mon Sep 17 00:00:00 2001 From: JW Jacobson <116485484+jwjacobson@users.noreply.github.com> Date: Tue, 18 Jun 2024 23:23:50 -0400 Subject: [PATCH 2/2] Create first draft of Sphinx user manual --- docs/about/appfocus.rst | 4 ++++ docs/about/future.rst | 14 ++++++++++++++ docs/about/index.rst | 11 +++++++++++ docs/about/whyjazztunes.rst | 8 ++++++++ docs/conf.py | 10 +++++++++- docs/index.rst | 23 ++++++++++++++++------- docs/using/adding.rst | 12 ++++++++++++ docs/using/index.rst | 11 +++++++++++ docs/using/managing.rst | 7 +++++++ docs/using/playing.rst | 11 +++++++++++ docs/using/searching.rst | 14 ++++++++++++++ tests/conftest.py | 2 +- 12 files changed, 118 insertions(+), 9 deletions(-) create mode 100644 docs/about/appfocus.rst create mode 100644 docs/about/future.rst create mode 100644 docs/about/index.rst create mode 100644 docs/about/whyjazztunes.rst create mode 100644 docs/using/adding.rst create mode 100644 docs/using/index.rst create mode 100644 docs/using/managing.rst create mode 100644 docs/using/playing.rst create mode 100644 docs/using/searching.rst diff --git a/docs/about/appfocus.rst b/docs/about/appfocus.rst new file mode 100644 index 0000000..62d8632 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/about/future.rst b/docs/about/future.rst new file mode 100644 index 0000000..a3a1fc6 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/about/index.rst b/docs/about/index.rst new file mode 100644 index 0000000..b955687 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/about/whyjazztunes.rst b/docs/about/whyjazztunes.rst new file mode 100644 index 0000000..e8b8b61 --- /dev/null +++ b/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 `_ and `popular `_ 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. \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index bc71ef0..0defe98 100644 --- a/docs/conf.py +++ b/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 + ], +} diff --git a/docs/index.rst b/docs/index.rst index 6e24476..5c6273f 100644 --- a/docs/index.rst +++ b/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 `_. + +The source code is available on `Github `_. .. 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` diff --git a/docs/using/adding.rst b/docs/using/adding.rst new file mode 100644 index 0000000..3cf02c8 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/using/index.rst b/docs/using/index.rst new file mode 100644 index 0000000..d4eba05 --- /dev/null +++ b/docs/using/index.rst @@ -0,0 +1,11 @@ +Using jazztunes +================ +To start using jazztunes, first create an account at `jazztunes.org `_. + +.. toctree:: + :maxdepth: 2 + + adding + managing + playing + searching \ No newline at end of file diff --git a/docs/using/managing.rst b/docs/using/managing.rst new file mode 100644 index 0000000..1b60ffa --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/using/playing.rst b/docs/using/playing.rst new file mode 100644 index 0000000..5a38ee3 --- /dev/null +++ b/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! + + + diff --git a/docs/using/searching.rst b/docs/using/searching.rst new file mode 100644 index 0000000..b647feb --- /dev/null +++ b/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. diff --git a/tests/conftest.py b/tests/conftest.py index f75dfe3..f7cd39c 100644 --- a/tests/conftest.py +++ b/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(