Update docs/developers/index.rst, docs/developers/subsonic.rst files

Deleted developers/index.rst, developers/subsonic.rst files

CHANGELOG

@@ -2203,7 +2203,7 @@ On both docker and non-docker setup, you'll also have to update your nginx
 configuration for websocket support. Ensure you have the following blocks
 included in your virtualhost file:
 
-.. code-block:: txt
+.. code-block:: text
 
     map $http_upgrade $connection_upgrade {
         default upgrade;

CONTRIBUTING.rst

@@ -353,9 +353,339 @@ Internationalization
 --------------------
 
 We're using https://github.com/Polyconseil/vue-gettext to manage i18n in the project.
+<<<<<<< HEAD
 When working on the front-end, any end-user string should be translated
 using either ``<translate>yourstring</translate>`` or ``$gettext('yourstring')``
 function.
+||||||| parent of 21fb39dd... Update docs/developers/index.rst, docs/developers/subsonic.rst files
+When working on the front-end, any end-user string should be marked as a translatable string,
+with the proper context, as described below.
+
+Translations in HTML
+^^^^^^^^^^^^^^^^^^^^
+
+Translations in HTML use the ``<translate>`` tag::
+
+    <template>
+      <div>
+        <h1><translate translate-context="Content/Profile/Header">User profile</translate></h1>
+        <p>
+          <translate
+            translate-context="Content/Profile/Paragraph"
+            :translate-params="{username: 'alice'}">
+            You are logged in as %{ username }
+          </translate>
+        </p>
+         <p>
+          <translate
+            translate-context="Content/Profile/Paragraph"
+            translate-plural="You have %{ count } new messages, that's a lot!"
+            :translate-n="unreadMessagesCount"
+            :translate-params="{count: unreadMessagesCount}">
+            You have 1 new message
+          </translate>
+        </p>
+      </div>
+    </template>
+
+Anything between the `<translate>` and `</translate>` delimiters will be considered as a translatable string.
+You can use variables in the translated string via the ``:translate-params="{var: 'value'}"`` directive, and reference them like this:
+``val value is %{ value }``.
+
+For pluralization, you need to use ``translate-params`` in conjunction with ``translate-plural`` and ``translate-n``:
+
+- ``translate-params`` should contain the variable you're using for pluralization (which is usually shown to the user)
+- ``translate-n`` should match the same variable
+- The ``<translate>`` delimiters contain the non-pluralized version of your string
+- The ``translate-plural`` directive contains the pluralized version of your string
+
+
+Translations in javascript
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Translations in javascript work by calling the ``this.$*gettext`` functions::
+
+    export default {
+      computed: {
+        strings () {
+          let tracksCount = 42
+          let playButton = this.$pgettext('Sidebar/Player/Button/Verb, Short', 'Play')
+          let loginMessage = this.$pgettext('*/Login/Message', 'Welcome back %{ username }')
+          let addedMessage = this.$npgettext('*/Player/Message', 'One track was queued', '%{ count } tracks were queued', tracksCount)
+          console.log(this.$gettextInterpolate(addedMessage, {count: tracksCount}))
+          console.log(this.$gettextInterpolate(loginMessage, {username: 'alice'}))
+        }
+      }
+    }
+
+The first argument of the ``$pgettext`` and ``$npgettext`` functions is the string context.
+
+Contextualization
+^^^^^^^^^^^^^^^^^
+
+Translation contexts provided via the ``translate-context`` directive and the ``$pgettext`` and ``$npgettext`` are never shown to end users
+but visible by Funkwhale translators. They help translators where and how the strings are used,
+especially with short or ambiguous strings, like ``May``, which can refer a month or a verb.
+
+While we could in theory use free form context, like ``This string is inside a button, in the main page, and is a call to action``,
+Funkwhale use a hierarchical structure to write contexts and keep them short and consistents accross the app. The previous context,
+rewritten correctly would be: ``Content/Home/Button/Call to action``.
+
+This hierarchical structure is made of several parts:
+
+- The location part, which is required and refers to the big blocks found in Funkwhale UI where the translated string is displayed:
+    - ``Content``
+    - ``Footer``
+    - ``Head``
+    - ``Menu``
+    - ``Popup``
+    - ``Sidebar``
+    - ``*`` for strings that are not tied to a specific location
+
+- The feature part, which is required, and refers to the feature associated with the translated string:
+    - ``About``
+    - ``Admin``
+    - ``Album``
+    - ``Artist``
+    - ``Embed``
+    - ``Home``
+    - ``Login``
+    - ``Library``
+    - ``Moderation``
+    - ``Player``
+    - ``Playlist``
+    - ``Profile``
+    - ``Favorites``
+    - ``Notifications``
+    - ``Radio``
+    - ``Search``
+    - ``Settings``
+    - ``Signup``
+    - ``Track``
+    - ``Queue``
+    - ``*`` for strings that are not tied to a specific feature
+
+- The component part, which is required and refers to the type of element that contain the string:
+    - ``Button``
+    - ``Card``
+    - ``Checkbox``
+    - ``Dropdown``
+    - ``Error message``
+    - ``Form``
+    - ``Header``
+    - ``Help text``
+    - ``Hidden text``
+    - ``Icon``
+    - ``Input``
+    - ``Image``
+    - ``Label``
+    - ``Link``
+    - ``List item``
+    - ``Menu``
+    - ``Message``
+    - ``Paragraph``
+    - ``Placeholder``
+    - ``Tab``
+    - ``Table``
+    - ``Title``
+    - ``Tooltip``
+    - ``*`` for strings that are not tied to a specific component
+
+The detail part, which is optional and refers to the contents of the string itself, such as:
+    - ``Adjective``
+    - ``Call to action``
+    - ``Noun``
+    - ``Short``
+    - ``Unit``
+    - ``Verb``
+
+Here are a few examples of valid context hierarchies:
+
+- ``Sidebar/Player/Button``
+- ``Content/Home/Button/Call to action``
+- ``Footer/*/Help text``
+- ``*/*/*/Verb, Short``
+- ``Popup/Playlist/Button``
+- ``Content/Admin/Table.Label/Short, Noun (Value is a date)``
+
+It's possible to nest multiple component parts to reach a higher level of detail. The component parts are then separated by a dot:
+
+- ``Sidebar/Queue/Tab.Title``
+- ``Content/*/Button.Title``
+- ``Content/*/Table.Header``
+- ``Footer/*/List item.Link``
+- ``Content/*/Form.Help text``
+
+Collecting translatable strings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to ensure your translatable strings are correctly marked for translation,
+you can try to extract them.
+
+When working on the front-end, any end-user string should be marked as a translatable string,
+with the proper context, as described below.
+
+Translations in HTML
+^^^^^^^^^^^^^^^^^^^^
+
+Translations in HTML use the ``<translate>`` tag::
+
+    <template>
+      <div>
+        <h1><translate translate-context="Content/Profile/Header">User profile</translate></h1>
+        <p>
+          <translate
+            translate-context="Content/Profile/Paragraph"
+            :translate-params="{username: 'alice'}">
+            You are logged in as %{ username }
+          </translate>
+        </p>
+         <p>
+          <translate
+            translate-context="Content/Profile/Paragraph"
+            translate-plural="You have %{ count } new messages, that's a lot!"
+            :translate-n="unreadMessagesCount"
+            :translate-params="{count: unreadMessagesCount}">
+            You have 1 new message
+          </translate>
+        </p>
+      </div>
+    </template>
+
+Anything between the `<translate>` and `</translate>` delimiters will be considered as a translatable string.
+You can use variables in the translated string via the ``:translate-params="{var: 'value'}"`` directive, and reference them like this:
+``val value is %{ value }``.
+
+For pluralization, you need to use ``translate-params`` in conjunction with ``translate-plural`` and ``translate-n``:
+
+- ``translate-params`` should contain the variable you're using for pluralization (which is usually shown to the user)
+- ``translate-n`` should match the same variable
+- The ``<translate>`` delimiters contain the non-pluralized version of your string
+- The ``translate-plural`` directive contains the pluralized version of your string
+
+
+Translations in javascript
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Translations in javascript work by calling the ``this.$*gettext`` functions::
+
+    export default {
+      computed: {
+        strings () {
+          let tracksCount = 42
+          let playButton = this.$pgettext('Sidebar/Player/Button/Verb, Short', 'Play')
+          let loginMessage = this.$pgettext('*/Login/Message', 'Welcome back %{ username }')
+          let addedMessage = this.$npgettext('*/Player/Message', 'One track was queued', '%{ count } tracks were queued', tracksCount)
+          console.log(this.$gettextInterpolate(addedMessage, {count: tracksCount}))
+          console.log(this.$gettextInterpolate(loginMessage, {username: 'alice'}))
+        }
+      }
+    }
+
+The first argument of the ``$pgettext`` and ``$npgettext`` functions is the string context.
+
+Contextualization
+^^^^^^^^^^^^^^^^^
+
+Translation contexts provided via the ``translate-context`` directive and the ``$pgettext`` and ``$npgettext`` are never shown to end users
+but visible by Funkwhale translators. They help translators where and how the strings are used,
+especially with short or ambiguous strings, like ``May``, which can refer a month or a verb.
+
+While we could in theory use free form context, like ``This string is inside a button, in the main page, and is a call to action``,
+Funkwhale use a hierarchical structure to write contexts and keep them short and consistents accross the app. The previous context,
+rewritten correctly would be: ``Content/Home/Button/Call to action``.
+
+This hierarchical structure is made of several parts:
+
+- The location part, which is required and refers to the big blocks found in Funkwhale UI where the translated string is displayed:
+    - ``Content``
+    - ``Footer``
+    - ``Head``
+    - ``Menu``
+    - ``Popup``
+    - ``Sidebar``
+    - ``*`` for strings that are not tied to a specific location
+
+- The feature part, which is required, and refers to the feature associated with the translated string:
+    - ``About``
+    - ``Admin``
+    - ``Album``
+    - ``Artist``
+    - ``Embed``
+    - ``Home``
+    - ``Login``
+    - ``Library``
+    - ``Moderation``
+    - ``Player``
+    - ``Playlist``
+    - ``Profile``
+    - ``Favorites``
+    - ``Notifications``
+    - ``Radio``
+    - ``Search``
+    - ``Settings``
+    - ``Signup``
+    - ``Track``
+    - ``Queue``
+    - ``*`` for strings that are not tied to a specific feature
+
+- The component part, which is required and refers to the type of element that contain the string:
+    - ``Button``
+    - ``Card``
+    - ``Checkbox``
+    - ``Dropdown``
+    - ``Error message``
+    - ``Form``
+    - ``Header``
+    - ``Help text``
+    - ``Hidden text``
+    - ``Icon``
+    - ``Input``
+    - ``Image``
+    - ``Label``
+    - ``Link``
+    - ``List item``
+    - ``Menu``
+    - ``Message``
+    - ``Paragraph``
+    - ``Placeholder``
+    - ``Tab``
+    - ``Table``
+    - ``Title``
+    - ``Tooltip``
+    - ``*`` for strings that are not tied to a specific component
+
+The detail part, which is optional and refers to the contents of the string itself, such as:
+    - ``Adjective``
+    - ``Call to action``
+    - ``Noun``
+    - ``Short``
+    - ``Unit``
+    - ``Verb``
+
+Here are a few examples of valid context hierarchies:
+
+- ``Sidebar/Player/Button``
+- ``Content/Home/Button/Call to action``
+- ``Footer/*/Help text``
+- ``*/*/*/Verb, Short``
+- ``Popup/Playlist/Button``
+- ``Content/Admin/Table.Label/Short, Noun (Value is a date)``
+
+It's possible to nest multiple component parts to reach a higher level of detail. The component parts are then separated by a dot:
+
+- ``Sidebar/Queue/Tab.Title``
+- ``Content/*/Button.Title``
+- ``Content/*/Table.Header``
+- ``Footer/*/List item.Link``
+- ``Content/*/Form.Help text``
+
+Collecting translatable strings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to ensure your translatable strings are correctly marked for translation,
+you can try to extract them.
+>>>>>>> 21fb39dd... Update docs/developers/index.rst, docs/developers/subsonic.rst files
 
 Extraction is done by calling ``yarn run i18n-extract``, which
 will pull all the strings from source files and put them in a PO file.

docs/upgrading/0.17.rst → docs/admin/0.17.rst

@@ -38,7 +38,7 @@ to help you understand the scale of the changes:
 +----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
 From a shared, instance-wide library to users libraries
-------------------------------------------------------
+-------------------------------------------------------
 
 As you can see, there is a big switch: in earlier versions, each instance had one big library,
 that was available to all its users. This model don't scale well (especially if you put

docs/configuration.rst → docs/admin/configuration.rst

@@ -14,7 +14,7 @@ and technical aspects of your instance, such as database credentials.
 
 .. note::
 
-    You should restart all funkwhale processes when you change the values
+    You should restart all Funkwhale processes when you change the values
     on environment variables.
 
 
@@ -38,7 +38,7 @@ settings in this interface.
 .. note::
 
     If you have any issue with the web application, a management interface is also
-    available for those settings from Django's administration interface. It's
+    available for those settings from :doc:`Django's administration interface <django>`. It's
     less user friendly, though, and we recommend you use the web app interface
     whenever possible.
 
@@ -110,7 +110,7 @@ for this value. For non-docker installation, you can use any absolute path.
 
 Default: :ref:`setting-MUSIC_DIRECTORY_PATH`
 
-When using Docker, the value of :ref:`MUSIC_DIRECTORY_PATH` in your containers
+When using Docker, the value of :ref:`setting-MUSIC_DIRECTORY_PATH` in your containers
 may differ from the real path on your host. Assuming you have the following directive
 in your :file:`docker-compose.yml` file::
 
@@ -156,7 +156,7 @@ permissions are:
   other instances, and accept/deny federation requests from other instances
 
 There is no dedicated interface to manage users permissions, but superusers
-can login on the Django's admin at ``/api/admin/`` and grant permissions
+can login on the :doc:`Django's admin <django>` at ``/api/admin/`` and grant permissions
 to users at ``/api/admin/users/user/``.
 
 Front-end settings

docs/admin/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/importing-music.rst → docs/admin/importing-music.rst

@@ -151,4 +151,4 @@ From other instances
 --------------------
 
 Funkwhale also supports importing music from other instances. Please refer
-to :doc:`federation` for more details.
+to :doc:`../federation/index` for more details.

docs/admin/index.rst

+Administrator Documentation
+=====================================
+
+This documentation is targeted at administrators of instances. This typically refers to
+the person(s) responsible for running the server and managing the software on a technical
+level.
+
+Setup Guides
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   ../installation/index
+   configuration
+   importing-music
+
+Administration
+--------------
+
+.. toctree::
+   :maxdepth: 2
+
+   django
+   url
+   upgrading
+
+Troubleshooting Issues
+----------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   troubleshooting

docs/troubleshooting.rst → docs/admin/troubleshooting.rst

@@ -14,7 +14,7 @@ Diagnose problems
 ^^^^^^^^^^^^^^^^^
 
 Funkwhale is made of several components, each one being a potential cause for failure. Having an even basic overview
-of Funkwhale's technical architecture can help you understand what is going on. You can refer to :doc:`the technical architecture </architecture>` for that.
+of Funkwhale's technical architecture can help you understand what is going on. You can refer to :doc:`the technical architecture <../developers/architecture>` for that.
 
 Problems usually fall into one of those categories:
 
@@ -28,54 +28,6 @@ Each category comes with its own set of diagnose tools and/or commands we will d
 steps for each type of problem. Please try those to see if it fix your issues. If none of those works, please report your issue on our
 issue tracker.
 
-Frontend issues
-^^^^^^^^^^^^^^^
-
-Diagnostic tools:
-
-- Javascript and network logs from your browser console (see instructions on how to open it in `Chrome <https://developers.google.com/web/tools/chrome-devtools/console/>`_ and  `Firefox <https://developer.mozilla.org/en-US/docs/Tools/Web_Console/Opening_the_Web_Console>`_
-- Proxy and API access and error logs (see :ref:`access-logs`)
-- The same operation works from a different browser
-
-Common problems
-***************
-
-The front-end is completely blank
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You are visiting Funkwhale, but you don't see anything.
-
-- Try from a different browser
-- Check network errors in your browser console. If you see responses with 40X or 50X statuses, there is probably an issue with the webserver configuration
-- If you don't see anything wrong in the network console, check the Javascript console
-- Disable your browser extensions (like adblockers)
-
-Music is not playing
-~~~~~~~~~~~~~~~~~~~~
-
-You have some tracks in your queue that don't play, or the queue is jumping from one track to the next until
-there is no more track available:
-
-- Try with other tracks. If it works with some tracks but not other tracks, this may means that the failing tracks are not probably imported
-  or that your browser does not support a specific audio format
-- Check the network and javascript console for potential errors
-
-Tracks are not appending to the queue
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When clicking on "Play", "Play all albums" or "Play all" buttons, some tracks are not appended to the queue. This is
-actually a feature of Funkwhale: those tracks have no file associated with them, so we cannot play them.
-
-Specific pages are loading forever or blank
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When viewing a given page, the page load never ends (you continue to see the spinner), or nothing seems to appear at all:
-
-- Ensure your internet connection is up and running
-- Ensure your instance is up and running
-- Check the network and javascript console for potential errors
-
-
 Backend issues
 ^^^^^^^^^^^^^^
 

docs/upgrading/index.rst → docs/admin/upgrading.rst

@@ -13,7 +13,7 @@ Upgrading your Funkwhale instance to a newer version
 Reading the release notes
 -------------------------
 
-Please take a few minutes to read the :doc:`changelog`: updates should work
+Please take a few minutes to read the :doc:`../changelog`: updates should work
 similarly from version to version, but some of them may require additional steps.
 Those steps would be described in the version release notes.
 
@@ -33,7 +33,7 @@ when possible.
 Docker setup
 ------------
 
-If you've followed the setup instructions in :doc:`Docker`, upgrade path is
+If you've followed the setup instructions in :doc:`../installation/docker`, upgrade path is
 easy:
 
 Mono-container installation

docs/admin/url.rst

+Changing Your Instance URL
+==========================
+
+At some point, you may wish to change your instance URL. In order to
+do this, you will need to change the following:
+
+- The instance URL in your .env file
+- The instance URL in your ``/etc/nginx/sites-enabled/funkwhale.conf`` or ``/etc/apache2/sites-enabled/funkwhale.conf`` depending on your web server setup
+- Any references to the old URL in your database
+
+The changes to the database can be achieved with the ``fix_federation_ids`` script in the ``manage.py``
+file. 
+
+Example output:
+
+.. code-block:: shell
+
+   # For Docker setups
+   docker-compose run --rm api python manage.py fix_federation_ids https://old-url https://new-url --no-dry-run --no-input
+
+   # For non-Docker setups
+   python manage.py fix_federation_ids https://old-url https://new-url --no-dry-run --no-input
+
+   # Output
+   Will replace 108 found occurences of 'https://old-url' by 'https://new-url':
+
+   - 20 music.Artist
+   - 13 music.Album
+   - 39 music.Track
+   - 31 music.Upload
+   - 1 music.Library
+   - 4 federation.Actor
+   - 0 federation.Activity
+   - 0 federation.Follow
+   - 0 federation.LibraryFollow
+
+   Replacing on 20 music.Artist…
+   Replacing on 13 music.Album…
+   Replacing on 39 music.Track…
+   Replacing on 31 music.Upload…
+   Replacing on 1 music.Library…
+   Replacing on 4 federation.Actor…
+   Replacing on 0 federation.Activity…
+   Replacing on 0 federation.Follow…
+   Replacing on 0 federation.LibraryFollow…
+
+On Docker Installations