Rearranging Files
=================

Sometimes, rearranging the layout of documents in the docs folder can help to make
things a bit clearer for users. However, this can present the following issues:

- :ref:`Orphaned document links <orphaned-doc>`
- :ref:`Orphaned URLs <orphaned-url>`

.. _orphaned-doc:

Orphaned Document Links
-----------------------

Documents frequently reference other documents to avoid repeating information. If you
move a document, you need to be sure to update any orphaned references.

Running ``make html`` in the ``docs`` directory (assuming you have :doc:`Sphinx installed <tools>`)
will generate a series of warnings letting you know if any links are orphaned.

.. code-block:: shell
   
   funkwhale/docs/documentation/rearrange.rst:17: WARNING: unknown document: setup

You can then go to the file/line in question and update the link to its new location.

.. _orphaned-url:

Orphaned URLs
-------------

Once internal document links have been resolved, it is important to consider that the
moved file may have also been linked externally elsewhere before. In order to ensure
that anybody trying to access the file is properly redirected to its new location, we
need to make use of the link redirector in the ``conf.py`` file.

The link redirector takes two arguments: the old location of the file (passed as a .html
file at the relative path ``docs``), and the new location it should redirect to. For example,
if a document was moved from ``docs/index.html`` to ``docs/admin/index.html``, we would add
the following to the ``redirect_files`` section of ``conf.py``:

.. code-block:: python

   # -- Build legacy redirect files -------------------------------------------

   # Define list of redirect files to be build in the Sphinx build process

   redirect_files = [

      ('index.html', 'admin/index.html')
    ]

If you are moving something from one folder to another, you would need to tell the redirect
to move to the correct level. For example, if a file is moving from ``docs/admin/index.html``
to ``docs/users/index.html``, you will need to add the following to the ``redirect_files``
section of ``conf.py``:

.. code-block:: python

   # -- Build legacy redirect files -------------------------------------------

   # Define list of redirect files to be build in the Sphinx build process

   redirect_files = [

      ('admin/index.html', '../users/index.html') #The '..' tells the script to go up a level
    ]

The script will then take these two arguments and create a redirect file in the original
location so that anybody accessing the existing URL will be redirected.