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:
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 Sphinx installed)
will generate a series of warnings letting you know if any links are orphaned.
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 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:
# -- 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:
# -- 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.