From 7d598dd38e01b81d03830988213bf26e987727b5 Mon Sep 17 00:00:00 2001 From: Sally Makin Date: Mon, 2 Dec 2024 11:43:31 +0000 Subject: [PATCH 1/3] Add Rediraffe support --- contributing/submit-contribution.rst | 21 ++++++++++++++++++++- custom_conf.py | 6 ++++++ redirects.txt | 9 +++++++++ 3 files changed, 35 insertions(+), 1 deletion(-) create mode 100644 redirects.txt diff --git a/contributing/submit-contribution.rst b/contributing/submit-contribution.rst index c1b58d56..a58ca40d 100644 --- a/contributing/submit-contribution.rst +++ b/contributing/submit-contribution.rst @@ -29,7 +29,26 @@ 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 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 there should be no preceding foward slash at the start of the path, +but there must be a trailing one at the end. See the +`Sphinx Rediraffe docs `_ +for more guidance, or reach out to us for help. Manual testing ============== diff --git a/custom_conf.py b/custom_conf.py index 5c302935..13e98694 100644 --- a/custom_conf.py +++ b/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/', diff --git a/redirects.txt b/redirects.txt new file mode 100644 index 00000000..31bb5536 --- /dev/null +++ b/redirects.txt @@ -0,0 +1,9 @@ +# Comment lines start with a hash (#) and are ignored +# Each redirect should appear on its own line +# Do not include a file extension +# Paths don't need a slash in front of them +# We are using the dirhtml builder so we need a trailing slash at the end +# The paths should match what's in the build directory +# Example: +# redirect/from redirect/to + From f8dbd07aa15266b77f2fc343b4b01f3f3942ec59 Mon Sep 17 00:00:00 2001 From: Sally Makin Date: Wed, 4 Dec 2024 10:58:41 +0000 Subject: [PATCH 2/3] Apply review feedback --- contributing/submit-contribution.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/contributing/submit-contribution.rst b/contributing/submit-contribution.rst index a58ca40d..28e20bad 100644 --- a/contributing/submit-contribution.rst +++ b/contributing/submit-contribution.rst @@ -35,8 +35,8 @@ 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 in the published -documentation. +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: @@ -45,8 +45,10 @@ root directory, in the following format: redirect/path/from/ redirect/path/to/ ``` -Note that there should be no preceding foward slash at the start of the path, -but there must be a trailing one at the end. See the +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 `_ for more guidance, or reach out to us for help. From 4566cd8e130963d2feac6d257bba9b2967da1c84 Mon Sep 17 00:00:00 2001 From: Sally Makin Date: Thu, 5 Dec 2024 10:04:02 +0000 Subject: [PATCH 3/3] Improve redirects instructions --- redirects.txt | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/redirects.txt b/redirects.txt index 31bb5536..dd215ee2 100644 --- a/redirects.txt +++ b/redirects.txt @@ -1,9 +1,16 @@ -# Comment lines start with a hash (#) and are ignored -# Each redirect should appear on its own line -# Do not include a file extension -# Paths don't need a slash in front of them -# We are using the dirhtml builder so we need a trailing slash at the end -# The paths should match what's in the build directory +# 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 redirect/to +# redirect/from/file/ redirect/to/file/ + +explanation/intro-to/ explanation/introduction-to/