Merge branch 'develop' into 'develop'

Added guides for Django backend, tagging music properly

See merge request funkwhale/funkwhale!623

docs/users/apps.rst

@@ -40,10 +40,10 @@ Those features as missing:
 
 .. note::
 
-    If you know or use some recent, well-maintained, Subsonic clients,
+    If you know or use some recent, well-maintained Subsonic clients,
     please get in touch so we can add them to this list.
 
-    Especially we're still lacking an iOS client!
+    In particular we're still lacking an iOS client!
 
 
 Enabling Subsonic on your Funkwhale account
@@ -160,7 +160,7 @@ Once installed, add the following to your /etc/mopidy/mopidy.conf::
     [subidy]
     enabled=True
     url=https://path.to/your/funkwhale/server
-    username=funkwhale
+    username=your_funkwhale_username
     password=your_subsonic_password
     #legacy_auth=(optional - setting to yes may solve some connection errors)
     #api_version=(optional - specify which API version to use. Subsonic 6.2 uses 1.14.0)

docs/users/django.rst

+Using the Django Administration Backend
+=========================
+
+Funkwhale is being actively developed, and new features are being added to the frontend all the time. However, there are some administrative tasks that can only be undertaken in the Django Administration backend.
+
+.. Warning::
+    Deleting items on the backend is **not** recommended. Deletions performed on the backend are permanent. If you remove something in the backend, you will need to re-add it from scratch.
+
+Accessing the Django Backend
+----------------------------
+
+To access your instance's backend, navigate to ``https://yourdomain/api/admin``. You will be prompted to log in. By default, the login details will be those of the priviliged user created during the setup process.
+
+Deleting Items
+-------------------
+
+By default, deleting items in the front end removes the file from the server but **does not** delete associated entities such as artists, albums, and track data, meaning that they will still be viewable but no longer playable. Items deleted in this way will also still count on the instance statistics. To remove them completely, it is necessary to remove them from the database entirely using the Django Administration backend.
+
+.. Warning::
+    Deleting tracks, albums, or artists will also remove them completely from any associated playlists, radios, or favorites lists. Before continuing, make sure other users on the instance are aware of the deletion(s).
+
+Deleting a Track
+^^^^^^^^^^^^^^^^
+
+* Navigate to ``https://yourdomain/api/admin/music/track``
+* Select the track(s) you wish to delete
+* In the ``Action`` dropdown menu, select "Delete Selected Items"
+* Click on "Go". You will be prompted to confirm the track's deletion
+
+Deleting an Album
+^^^^^^^^^^^^^^^^^^
+
+* Navigate to ``https://yourdomain/api/admin/music/album``
+* Select the album(s) you wish to delete
+* In the ``Action`` dropdown menu, select "Delete Selected Items"
+* Click on "Go". You will be prompted to confirm the album's deletion
+
+.. note::
+
+    Deleting an album will remove all tracks associated with the album
+
+Deleting an Artist
+^^^^^^^^^^^^^^^^^^
+
+* Navigate to ``https://yourdomain/api/admin/music/artist``
+* Select the artist(s) you wish to delete
+* In the ``Action`` dropdown menu, select "Delete Selected Items"
+* Click on "Go". You will be prompted to confirm the artist's deletion
+
+.. note::
+
+    Deleting an artist will remove all tracks and albums associated with the artist
+
+Removing a Followed Library
+---------------------------
+
+In Funkwhale, unfollowing a library will leave the items in place but inaccessible. To completely remove them:
+
+* Navigate to ``https://yourdomain/api/admin/music/library/``
+* Tick the box next to the library you wish to remove
+* In the ``Action`` dropdown menu, select "Delete Selected Items"
+* Click on "Go". You will be prompted to confirm the library's deletion
+
+Adding Missing Album Art
+-------------------------
+
+Sometimes album art can fail to appear despite music being properly tagged. When this happens, it is possible to replace the missing art.
+
+* Navigate to ``https://yourdomain/api/admin/music/album``
+* Search for and select the album in question
+* Find the item marked "Cover"
+* Click "Browse" and select the file from your computer
+* Click "Save" to confirm the changes
+
+The album art will now be present on the frontend.
+
+.. note::
+
+    You can also clear currently loaded album art by checking the checkbox next to the current item and selecting "Clear"

docs/users/index.rst

@@ -15,3 +15,5 @@ Funkwhale's users documentation
 
    apps
    upload
+   tagging
+   django

docs/users/tagging.rst

+Tagging Music With MusicBrainz Picard
+=====================================
+
+In order to get the most out of Funkwhale, it is important to tag files correctly. Good tagging makes managing your library much easier and provides Funkwhale with the information necessary to display album art, metadata, and other useful information. The recommended tool for tagging music is `MusicBrainz Picard <https://picard.musicbrainz.org/>`_.
+
+Tagging Items
+--------------
+
+Tagging a File
+^^^^^^^^^^^^^^
+
+To load a file into MusicBrainz Picard:
+
+* Click on "Add Files"
+* Select the files you want to tag from your computer
+* Picard should automatically start scanning the items. If nothing happenes, select the item(s) and click on "Scan"
+* Picard will start assigning suitable tags
+* Hit ctrl+s or click "Save" to save the tags to the file
+
+Tagging a Directory
+^^^^^^^^^^^^^^^^^^^
+
+* Click on "Add Folder"
+* Select the directory of files you want to tag from your computer
+* Picard should automatically start scanning the items. If nothing happenes, select the item(s) and click on "Scan"
+* Picard will start assigning suitable tags
+* Hit ctrl+s or click "Save" to save the tags to the file
+
+
+Alternative Versions
+--------------------
+
+Picard is generally accurate when it comes to determining the release of an album/track, but sometimes it can fail to get the right version. You can force it to use a particular version of an album or track using the following method:
+
+Alternative Albums
+^^^^^^^^^^^^^^^^^^
+
+* Load the directory into Picard
+* Once it has tagged the full album, right-click on the album and hover over "other versions"
+* Select the collect release from the list
+* Do this for any duplicate items until all tracks are under the correct release
+* Hit ctrl+s or click "Save" to save the tags to the files
+
+Alternative Tracks
+^^^^^^^^^^^^^^^^^^
+
+If a track is not picking up its release, do the following:
+
+* Right-click on the offending track and select "Search for Similar Tracks..."
+* Search for your release using `MusicBrainz's search syntax <https://musicbrainz.org/doc/Indexed_Search_Syntax>`_
+* Select the correct track from the list and click on "Load into Picard"
+* The track will now inherit tags from the selected track. Hit ctrl+s or click "Save" to save the tags to the file
+
+Adding Items to MusicBrainz
+---------------------------
+
+MusicBrainz is an ever-growing library of music, but it may not yet have an entry for certain items. You can add these yourself by following their `guide <https://musicbrainz.org/doc/How_to_Add_a_Release/>`_.
+
+Once you've added a new item, Picard should automatically pick up the new details based on the files' metadata. This means that it will tag the music not only for you, but for any other user who tries to tag the same item in the future.
\ No newline at end of file