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

@@ -512,7 +512,7 @@ It's possible to nest multiple component parts to reach a higher level of detail
 - ``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.

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/users/django.rst → 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.
 
@@ -28,7 +28,7 @@ Deleting a Track
 * 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

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
+-----------------------
+
+If you have followed the :doc:`Docker installation instructions <../installation/docker>`, you
+will need to do the following:
+
+- Edit your .env file to change the ``FUNKWHALE_HOSTNAME``  and ``DJANGO_ALLOWED_HOSTS`` value to your new URL
+- Edit your ``/etc/nginx/sites-enabled/funkwhale.conf`` file to change the ``server_name`` values to your new URL
+- Run the following command to change all mentions of your old instance URL in the database:
+
+.. code-block:: shell
+
+   docker-compose run --rm api python manage.py fix_federation_ids https://old-url https://new-url --no-dry-run --no-input
+
+- Restart Nginx or Apache to pick up the new changes
+
+.. code-block:: shell
+
+   # For Nginx
+   sudo systemctl restart nginx
+
+   # For Apache
+   sudo systemctl restart apache2
+
+On Non-Docker Installations
+---------------------------
+
+If you have followed the :doc:`non-docker setup <../installation/debian>`, you will need to do the following:
+
+- Edit your .env file to change the ``FUNKWHALE_HOSTNAME``  and ``DJANGO_ALLOWED_HOSTS`` value to your new URL
+- Edit your ``/etc/nginx/sites-enabled/funkwhale.conf`` file to change the ``server_name`` values to your new URL
+- Run the following command to change all mentions of your old instance URL in the database:
+
+.. code-block:: shell
+
+   python manage.py fix_federation_ids https://old-url https://new-url --no-dry-run --no-input
+
+- Restart Nginx or Apache to pick up the new changes
+
+.. code-block:: shell
+
+   # For Nginx
+   sudo systemctl restart nginx
+
+   # For Apache
+   sudo systemctl restart apache2
+   
\ No newline at end of file

docs/conf.py

@@ -19,6 +19,8 @@
 #
 import os
 import sys
+import datetime
+from shutil import copyfile
 
 sys.path.insert(0, os.path.abspath("../api"))
 
@@ -48,8 +50,9 @@ source_suffix = ".rst"
 master_doc = "index"
 
 # General information about the project.
+year = datetime.datetime.now().year
 project = "funkwhale"
-copyright = "2017, Eliot Berriot"
+copyright = "{}, Eliot Berriot".format(year)
 author = "Eliot Berriot"
 
 # The version info for the project you're documenting, acts as replacement for
@@ -81,7 +84,6 @@ pygments_style = "sphinx"
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -100,7 +102,6 @@ html_theme = "alabaster"
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
-
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
@@ -155,3 +156,48 @@ texinfo_documents = [
         "Miscellaneous",
     )
 ]
+
+# -- Build legacy redirect files -------------------------------------------
+
+# Define list of redirect files to be build in the Sphinx build process
+
+redirect_files = [
+
+    ('importing-music.html', 'admin/importing-music.html'),
+    ('architecture.html', 'developer/architecture.html'),
+    ('troubleshooting.html', 'admin/troubleshooting.html'),
+    ('configuration.html', 'admin/configuration.html'), 
+    ('upgrading/index.html', '../admin/upgrading.html'),
+    ('upgrading/0.17.html', '../admin/0.17.html'),
+    ('users/django.html', '../admin/django.html'),
+
+]
+
+# Generate redirect template
+
+redirect_template = """\
+<html>
+  <head>
+    <meta http-equiv="refresh" content="1; url={new}" />
+    <script>
+      window.location.href = "{new}"
+    </script>
+  </head>
+</html>
+"""
+
+# Tell Sphinx to copy the files
+
+def copy_legacy_redirects(app, docname):
+    if app.builder.name == 'html':
+        for html_src_path, new in redirect_files:
+            page = redirect_template.format(new=new)
+            target_path = app.outdir + '/' + html_src_path
+            if not os.path.exists(os.path.dirname(target_path)):
+               os.makedirs(os.path.dirname(target_path))
+            with open(target_path, 'w') as f:
+               f.write(page)
+
+
+def setup(app):
+    app.connect('build-finished', copy_legacy_redirects)

docs/architecture.rst → docs/developers/architecture.rst

@@ -50,7 +50,7 @@ or persist data.
 Third-party apps
 ----------------
 
-Since Funkwhale implements a subset of the Subsonic API, it's compatible with existing apps such
+Since Funkwhale implements a subset of the Subsonic API, it's compatible with existing :doc:`apps <../users/apps>` such
 as DSub, Ultrasonic or Clementine that support this API. Those apps can be used as a replacement
 or in conjunction of the web interface, but the underlying data is the same.
 

docs/developers/index.rst

@@ -10,6 +10,7 @@ Reference
 .. toctree::
    :maxdepth: 2
 
+   architecture
    ../api
    ../federation/index
    subsonic

docs/developers/subsonic.rst

@@ -57,7 +57,6 @@ in our payload, which you can use to adapt your client behaviour if needed:
 
     {
         "subsonic-response": {
-            ...
             "type": "funkwhale",
             "funkwhaleVersion": "0.17"
         }

docs/features.rst

@@ -24,7 +24,7 @@ Funkwhale is not bundled with any music, and you'll have to import your own musi
 
 At the moment, you can feed your existing music library to the server either by uploading it or by using :ref:`in-place-import` from a server-side directory. Assuming the files have the correct tags defined, they will be imported seamlessly.
 
-You can also access music being made available by other Funkwhale instances using :doc:`federation`.
+You can also access music being made available by other Funkwhale instances using :doc:`/federation/index`.
 
 Metadata
 ---------

docs/federation/index.rst

@@ -317,7 +317,7 @@ Supported on
 - :ref:`object-Library` objects
 
 Example (on :ref:`object-Library`)
-************************
+**********************************
 
 .. code-block:: json
 
@@ -339,7 +339,7 @@ Example (on :ref:`object-Library`)
   }
 
 Example (on :ref:`object-audio`)
-**********************
+********************************
 
 .. code-block:: json
 

docs/index.rst

@@ -11,14 +11,10 @@ Funkwhale is a self-hosted, modern free and open-source music server, heavily in
 .. toctree::
    :maxdepth: 2
 
-   users/index
    features
-   architecture
-   installation/index
-   upgrading/index
-   configuration
-   troubleshooting
-   importing-music
+   users/index
+   moderator/index
+   admin/index
    developers/index
    third-party
    contributing

docs/installation/debian.rst

@@ -207,6 +207,7 @@ You can then edit the file: the file is heavily commented, and the most relevant
 configuration options are mentioned at the top of the file.
 
 .. code-block:: shell
+
     nano /srv/funkwhale/api/.env
 
 Paste the secret key you generated earlier at the entry

docs/installation/docker.rst

@@ -196,4 +196,4 @@ Now, you just need to configure your :ref:`reverse-proxy <reverse-proxy-setup>`.
 About music acquisition
 -----------------------
 
-If you want to :doc:`import music located on the server </importing-music>`, you can put it in the ``data/music`` directory and it will become readable by the importer.
+If you want to :doc:`import music located on the server <../admin/importing-music>`, you can put it in the ``data/music`` directory and it will become readable by the importer.

docs/installation/external_dependencies.rst

@@ -93,6 +93,6 @@ On Arch Linux and its derivatives:
 This should be enough to have your redis server set up.
 
 External Authentication (LDAP)
-----------------------
+------------------------------
 
 LDAP support requires some additional dependencies to enable. On the OS level both ``libldap2-dev`` and ``libsasl2-dev`` are required, and the Python modules ``python-ldap`` and ``python-django-auth-ldap`` must be installed. These dependencies are all included in the ``requirements.*`` files so deploying with those will install these dependencies by default. However, they are not required unless LDAP support is explicitly enabled. See :doc:`./ldap` for more details.