Merge pull request #20 from JOJ0/cmd23-docs

Fix docs (CLI rewrite), fix rtd build, state AcousticBrainz shutdown in README

.readthedocs.yaml

@@ -0,0 +1,24 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: sphinx/source/conf.py
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: ./sphinx_requirements.txt
+    - method: pip
+      path: .

README.md

@@ -8,7 +8,7 @@
 D i s c o  /                /        /  - The geekiest DJ tool on the planet
           /_______/\_______/________/
 ```
-DiscoDOS helps a DJ remember and analyze what they played in their sets, or what they could possibly play in the future. It's based on data pulled from a users [Discogs](https://www.discogs.com) record [collection](https://support.discogs.com/hc/en-us/articles/360007331534-How-Does-The-Collection-Feature-Work-). Tracks can be organized into playlists and mix-transitions rated. Additionally the collection can be linked to the online music information services [MusicBrainz](https://musicbrainz.org) and [AcousticBrainz](https://acousticbrainz.org), thus further information (like musical key and BPM) is made available to the user.
+DiscoDOS helps a DJ remember and analyze what they played in their sets, or what they could possibly play in the future. It's based on data pulled from a users [Discogs](https://www.discogs.com) record [collection](https://support.discogs.com/hc/en-us/articles/360007331534-How-Does-The-Collection-Feature-Work-). Tracks can be organized into playlists and mix-transitions rated. Additionally the collection can be linked to the online music information services [MusicBrainz](https://musicbrainz.org) ~~and [AcousticBrainz](https://acousticbrainz.org), thus further information (like musical key and BPM) is made available to the user~~.
 
 DiscoDOS currently is available as a command line tool only, though prototypes of a mobile and a desktop app exist already. Despite of what the name implies, it's just the look that is reminiscent of the 80s/90s operating system, its usability follows most standards of a typical [shell](https://en.wikipedia.org/wiki/Shell_(computing)#Unix-like_systems) utility you would find on a [UNIX-like operating system](https://en.wikipedia.org/wiki/Unix-like).
 
@@ -19,6 +19,10 @@ DiscoDOS primarily aims at the Vinyl DJ but feature ideas for DJ's playing both,
 The following animated GIFs should give you an idea on how DiscoDOS looks and feels:
 
 
+_**Note: As of February 2022 unfortunately [the AcousticBrainz project was shut down](https://blog.metabrainz.org/2022/02/16/acousticbrainz-making-a-hard-decision-to-end-the-project/), as a consequence DiscoDOS can't fetch key and BPM anymore. Below videos are outdated and show some of those features.**_
+
+_**Note: Find some ideas on how DiscoDOS could solve this problem [in the website's roadmap chapter](https://discodos.jojotodos.net/#roadmap).**_
+
 
 <!-- omit in toc -->
 ##### Viewing mix details, searching and adding track:

sphinx/source/CONTRIBUTION.md

@@ -77,7 +77,7 @@ Install the necessary dependencies into your environment:
 
 Launch DiscoDOS' main command and follow the steps shown:
 
-`disco`
+`dsc`
 
 _**Note: Make sure you always first activate your virtual environment when coming back to developing or using DiscoDOS:**_
 
@@ -116,13 +116,13 @@ Install the necessary dependencies into your virtual environment:
 Some command wrappers should have been installed too. Verify if they exist inside your `~/.venvs/discodos/bin` directory:
 
 ```
-which disco
+which dsc
 which discosync
 ```
 
 Launch DiscoDOS' main command and follow the steps shown:
 
-`disco`
+`dsc`
 
 _**Note: Make sure you always first activate your virtual environment when coming back to developing or using DiscoDOS:**_
 
@@ -158,19 +158,19 @@ Install DiscoDOS into your user's Python environment:
 Some command wrappers should have been installed. Verify if they exist:
 
 ```
-which disco
+which dsc
 which discosync
 ```
 
 If `which` didn't find those commands, make sure your $PATH environment variable contains the path the wrappers where installed to. Usually this is `~/.local/bin/`
 
-_Note: On Debian-based systems there might be a file `/usr/bin/disco` on your system already provided by package mono-devel, thus depending on the order of paths in `$PATH`, `/usr/bin/disco` might be found before the DiscoDOS wrapper. Change `$PATH` to first search in `~/.local/bin` (export it in `.zshrc`, `.bashrc` or whatever shell you are using)_
+_Note: On Debian-based systems there might be a file `/usr/bin/dsc` on your system already provided by package mono-devel, thus depending on the order of paths in `$PATH`, `/usr/bin/dsc` might be found before the DiscoDOS wrapper. Change `$PATH` to first search in `~/.local/bin` (export it in `.zshrc`, `.bashrc` or whatever shell you are using)_
 
 Launch DiscoDOS' main command:
 
-`disco`
+`dsc`
 
-On first launch, `disco` will create a configuration file for you. To access your Discogs collection, an access token has to be generated and put into the file. Follow the steps in chapter [Configure Discogs API access](INSTALLATION.md#configure-discogs-api-access), then come back here!
+On first launch, `dsc` will create a configuration file for you. To access your Discogs collection, an access token has to be generated and put into the file. Follow the steps in chapter [Configure Discogs API access](INSTALLATION.md#configure-discogs-api-access), then come back here!
 
 Now that you've put the token into the configuration file, DiscoDOS completes setup by creating a local database (the DiscoBASE).
 
@@ -180,7 +180,7 @@ If the connection to Discogs is working, setup asks you to view a little tutoria
 
 Your starting point for further documentation is the [Quickstart Guide](QUICKSTART.md#importing-your-discogs-collection). Your next logical step is importing your Discogs collection.
 
-**Note: The `disco` and `discosync` commands are now installed globally and will work in any terminal emulator.**
+**Note: The `dsc` and `discosync` commands are now installed globally and will work in any terminal emulator.**
 
 **Note: DiscoDOS generates the following files which are kept in `~/.discodos/`:**
 

sphinx/source/INSTALLATION.md

@@ -26,9 +26,9 @@ Download the latest Windows installer (`DiscoDOS_version.exe`) from the [release
 
 Click Start Menu - DiscoDOS - DiscoDOS
 
-A new command prompt window opens and the DiscoDOS main command `disco` runs automatically.
+A new command prompt window opens and the DiscoDOS main command `dsc` runs automatically.
 
-On first launch, `disco` will create a configuration file for you. To access your Discogs collection, an access token has to be generated and put into the file. Follow the steps in chapter [Configure Discogs API access](#configure-discogs-api-access), then come back here!
+On first launch, `dsc` will create a configuration file for you. To access your Discogs collection, an access token has to be generated and put into the file. Follow the steps in chapter [Configure Discogs API access](#configure-discogs-api-access), then come back here!
 
 
 Now that you've put the token into the configuration file, DiscoDOS completes setup by creating a local database (the DiscoBASE).
@@ -39,7 +39,7 @@ If the connection to Discogs is working, setup asks you to view a little tutoria
 
 Your starting point for further documentation is the [Quickstart Guide](QUICKSTART.md#importing-your-discogs-collection). Your next logical step is importing your Discogs collection.
 
-**Note: The `disco` and `discosync` commands are installed globally, you can use the Start Menu entry to run them but they also work in any cmd.exe window.**
+**Note: The `dsc` and `discosync` commands are installed globally, you can use the Start Menu entry to run them but they also work in any cmd.exe window.**
 
 
 **Note: DiscoDOS generates the following files which are kept in `C:\Users\your_name\Documents\discodos\` (path may vary depending on your OS-language):**
@@ -60,7 +60,7 @@ I would highly recommend installing "Microsoft Windows Terminal". It will provid
    - or one of the preview version (I'd recommend them, they are usually stable enough!)
 
 ##### Some features worth trying out
-  - Zoom in/out (resize terminal text) using "ctrl + mouse wheel" (e.g handy when showing mixes in verbose view (`disco mix mix_name -v`)
+  - Zoom in/out (resize terminal text) using "ctrl + mouse wheel" (e.g handy when showing mixes in verbose view (`dsc mix mix_name -v`)
     - Alternatively zoom in/out using "ctrl +/ctrl -"
   - Paste text from clipboard using "right/secondary mouse button"
   - Command completion using "tab key" (cmd.exe had this already, yes - anyway it feels a little better here IMHO)
@@ -77,9 +77,9 @@ Doubleclick the .dmg file - Drag and drop `DiscoDOS.app` to `Applications` folde
 
 Launch DiscoDOS.app
 
-A new Terminal window opens and the DiscoDOS main command `disco` runs automatically.
+A new Terminal window opens and the DiscoDOS main command `dsc` runs automatically.
 
-On first launch, `disco` will create a configuration file for you. To access your Discogs collection, an access token has to be generated and put into the file. Follow the steps in chapter [Configure Discogs API access](#configure-discogs-api-access), then come back here!
+On first launch, `dsc` will create a configuration file for you. To access your Discogs collection, an access token has to be generated and put into the file. Follow the steps in chapter [Configure Discogs API access](#configure-discogs-api-access), then come back here!
 
 Now that you've put the token into the configuration file, DiscoDOS completes setup by creating a local database (the DiscoBASE).
 
@@ -89,7 +89,7 @@ If the connection to Discogs is working, setup asks you to view a little tutoria
 
 Your starting point for further documentation is the [Quickstart Guuide](QUICKSTART.md#importing-your-discogs-collection). Your next logical step is importing your Discogs collection.
 
-**Note: The `disco` and `discosync` commands are now installed globally, you can launch DiscoDOS.app to open a Terminal but they also work in any other Terminal window.**
+**Note: The `dsc` and `discosync` commands are now installed globally, you can launch DiscoDOS.app to open a Terminal but they also work in any other Terminal window.**
 
 **Note: DiscoDOS generates the following files which are kept in `/Users/your_name/Documents/DiscoDOS/`:**
 
@@ -115,7 +115,7 @@ To access your Discogs collection you need to generate an API login token and pu
 - Select _Settings_
 - Switch to section _Developers_
 - Click _Generate new token_
-- Run `disco` - you'll be prompted to put in the token.
+- Run `dsc` - you'll be prompted to put in the token.
 
 **Note: If you are updating from a previous DiscoDOS version, your config.yaml is existing and has a token set up already, thus you won't be bothered!**