Merge pull request #90 from s-makin/redirects

Add Rediraffe support

contributing/submit-contribution.rst

@@ -29,7 +29,28 @@ You can run:
    make linkcheck
    
 To perform a full spelling and link check. You can also run ``make`` by itself
-to see a list of all the possible ``make`` targets. 
+to see a list of all the possible ``make`` targets.
+
+Check if you need redirects
+===========================
+
+If you rename, move or delete an existing file, a corresponding redirect must
+be created to ensure users don't run into 404 errors when clicking links in the
+published documentation.
+
+To set up a redirect, add a line to the end of the `redirects.txt` file in the
+root directory, in the following format:
+
+```
+redirect/path/from/ redirect/path/to/
+```
+
+Note that since we use `dirhtml` to build, the built documentation is in the
+format `path/to/file/index.html` where `file` corresponds to the file name
+you are redirecting. This means that you only need a trailing slash at the end
+of the file name, without the file extension. See the
+`Sphinx Rediraffe docs <https://sphinxext-rediraffe.readthedocs.io/en/latest/>`_
+for more guidance, or reach out to us for help.
 
 Manual testing
 ==============

custom_conf.py

@@ -167,6 +167,7 @@
     'myst_parser',
     'sphinxcontrib.jquery',
     'sphinxcontrib.mermaid',
+    'sphinxext.rediraffe',
 #    'canonical.youtube-links',
 #    'canonical.related-links',
 #    'canonical.custom-rst-roles',
@@ -183,8 +184,13 @@
 # sphinxext-opengraph
 custom_required_modules = [
     'sphinxcontrib-mermaid',
+    'sphinxext-rediraffe',
 ]
 
+# Add redirects, so they can be updated here to land with docs being moved
+rediraffe_branch = "main"
+rediraffe_redirects = "redirects.txt"
+
 # Add files or directories that should be excluded from processing.
 custom_excludes = [
     'cheatsheets/',

redirects.txt

@@ -0,0 +1,16 @@
+# The redirects.txt file stores all the redirects for the published docs
+# If you change a filename, move or delete a file, you need a redirect here.
+# - Comment lines start with a hash (#) and are ignored
+# - Each redirect should appear on its own line
+
+# We are using the dirhtml builder, so files are treated as directories:
+# - A file is built like `filename/index.html`, not `filename.html`
+# - *Do* include a trailing slash at the end of the path
+# - *Do not* include a file extension or you'll get errors
+# - Paths don't need a slash in front of them
+
+# Example:
+# redirect/from/file/ redirect/to/file/
+
+explanation/intro-to/ explanation/introduction-to/
+