Repository: jupyterhub/jupyterhub

Issue:
How do we work with documentation redirects from rediraffe in the repo?
[...] to make a decision on what to do with regards to how we work with the redirects in this repo for now. If experience is gained and you start feeling confident on a practice, we try go for that more systematically in other repos long term.

I think the options on how to work with the redirects are:

1. Fully manual as now, where we figure out ourselves if we need to add a redirect
2. Mostly manual, where we can go fully manual but also suggest that `make rediraffecheckdiff` can be used to get informed on what redirects we should make.
3. Semi automated, where we suggest using `make rediraffewritediff` to update a file (not overwrite right?)
4. Mostly automated, where we have a github workflow triggered when docs change to inspect if a redirect needs to be setup and otherwise fails to let us know.
5. Almost fully automated, where we also push a commit with the relevant redirects.

If I understand this correctly, we need to consider this ourselves no matter what because the tools can't figure it out fully in all cases. That makes me think we shouldn't go for option 5. Maybe option 2-4? No matter what, I'm a big :+1: for going for something you feel like going for!

_Originally posted by @consideRatio in https://github.com/jupyterhub/jupyterhub/pull/4331#discussion_r1092331738_
            


Discussion:
Thank you for opening your first issue in this project! Engagement like this is essential for open source projects! :hugs:
<br>If you haven't done so already, check out [Jupyter's Code of Conduct](https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md). Also, please try to follow the issue template as it helps other other community members to contribute more effectively.
![welcome](https://raw.githubusercontent.com/jupyterhub/.github/master/images/welcome.jpg)
You can meet the other [Jovyans](https://jupyter.readthedocs.io/en/latest/community/content-community.html?highlight=jovyan#what-is-a-jovyan) by joining our [Discourse forum](http://discourse.jupyter.org/). There is also an intro thread there where you can stop by and say Hi! :wave:
<br>Welcome to the Jupyter community! :tada:

I agree that 2-4 is probably right. We already test docs builds with `make linkcheck`, so adding `make rediraffecheckdiff` [here](https://github.com/jupyterhub/jupyterhub/blob/9de3757caa4b3712c101bede3424583be7a57b6b/.github/workflows/test-docs.yml#L71-L74) is a small change and makes sense to me. We might even want the `rediraffe_branch` to get the head from the CI environment variable, rather than `main` which might get confused if there are other merged PRs with redirect changes (unlikely). I'd have to know more about how often `writediff`, but you can always _try_ `writediff` and override manually after checking its output, I imagine.


Resolving patch:
diff --git a/docs/source/conf.py b/docs/source/conf.py
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -235,8 +235,12 @@ def setup(app):
 # If you are basing changes off another branch/ commit, always change back
 # rediraffe_branch to main before pushing your changes upstream.
 #
-rediraffe_branch = "main"
+rediraffe_branch = os.environ.get("REDIRAFFE_BRANCH", "main")
 rediraffe_redirects = "redirects.txt"
+
+# allow 80% match for autogenerated redirects
+rediraffe_auto_redirect_perc = 80
+
 # rediraffe_redirects = {
 # "old-file": "new-folder/new-file-name",
 # }


Test patch: