Skip to contentSkip to conversation

docs: redirect from old arch to the new one

PATCH In review Costa Shulyupin 3 participants 7 messages Apr 27, 2023 – Apr 30, 2023 1 message not in the archive

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: redirect from old arch to the new one

Due to a recent reorganization of 'CPU Architectures', the links to the documentation from external resources were rendered invalid. This is a common challenge when attempting to make changes while maintaining backward compatibility. To address this issue, a commit has been made which uses sphinx extension to seamlessly redirect users from the old location of the page to the new one.

---
 Documentation/conf.py                 | 8 +++++++-
 Documentation/sphinx/requirements.txt | 1 +
 2 files changed, 8 insertions(+), 1 deletion(-)
Documentation/conf.py +7 -1
index 37314afd1ac8..514bfe6a8166 100644
@@ -55,7 +55,13 @@ needs_sphinx = '1.7'
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
-              'kernel_abi', 'kernel_feat']
+              'kernel_abi', 'kernel_feat',
+              'sphinx_reredirects',
+]
+
+redirects = {
+     "arch.html": "arch/index.html",
+}
 
 if major >= 3:
     if (major > 3) or (minor > 0 or patch >= 2):
Documentation/sphinx/requirements.txt +1 -0
index 335b53df35e2..0b067e985edb 100644
@@ -1,3 +1,4 @@
 # jinja2>=3.1 is not compatible with Sphinx<4.0
 jinja2<3.1
 Sphinx==2.4.4
+sphinx_reredirects
Signature · 1 line
2.40.0
maintainer
#1 lore raw
Quoted 20 lines · Costa Shulyupin

Due to a recent reorganization of 'CPU Architectures', the links to the documentation from external resources were rendered invalid. This is a common challenge when attempting to make changes while maintaining backward compatibility. To address this issue, a commit has been made which uses sphinx extension to seamlessly redirect users from the old location of the page to the new one.

---
 Documentation/conf.py                 | 8 +++++++-
 Documentation/sphinx/requirements.txt | 1 +
 2 files changed, 8 insertions(+), 1 deletion(-)
Documentation/conf.py +0 -0
index 37314afd1ac8..514bfe6a8166 100644
@@ -55,7 +55,13 @@ needs_sphinx = '1.7'
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',

Documentation/conf.py needs_sphinx = '1.7' · line 64

Quoted 10 lines
Documentation/conf.py +7 -1
               'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
-              'kernel_abi', 'kernel_feat']
+              'kernel_abi', 'kernel_feat',
+              'sphinx_reredirects',
+]
+
+redirects = {
+     "arch.html": "arch/index.html",
+}

I am not generally opposed to doing this, but:

- It only solves part of the problem; links directly into (say) the x86 docs will still break.

- Is there really a problem? Are there to-be-broken links out there that you can point to?

Thanks,

jon

A message that is not in the archive (sent off-list or not yet received): CADDUTFwGHytziCux07cXO0eYDUXYh3Scp=Qm96N+1wAX3ELDeg@mail.gmail.com

maintainer
#3 lore raw
Quoted 5 lines · Costa Shulyupin

My initial focus is on addressing conceptual review comments with this first fix. Once that is done, I intend to submit fixes for the remaining architecture. Furthermore, I intend to courteously with redirects relocate additional subdirectories. For example, consolidate subsystems.

Please do not top-post on kernel lists.

I'm not quite sure what "conceptual review comments" you're referring to. In any case, you have not answered my question: is there an actual problem needing to be solved here?

Thanks,

jon

#4 lore raw
Quoted 1 line

is there an actual problem needing to be solved here?

There is not an actual problem. Only a potential.

Thanks,
Costa

#5 lore raw
In reply to Costa Shulyupin

Em Thu, 27 Apr 2023 13:12:39 +0300
Costa Shulyupin <[email protected]> escreveu:

Quoted 19 lines

Due to a recent reorganization of 'CPU Architectures', the links to the documentation from external resources were rendered invalid. This is a common challenge when attempting to make changes while maintaining backward compatibility. To address this issue, a commit has been made which uses sphinx extension to seamlessly redirect users from the old location of the page to the new one.

---
 Documentation/conf.py                 | 8 +++++++-
 Documentation/sphinx/requirements.txt | 1 +
 2 files changed, 8 insertions(+), 1 deletion(-)
Documentation/conf.py +0 -0
index 37314afd1ac8..514bfe6a8166 100644

Documentation/conf.py needs_sphinx = '1.7' · line 60

Quoted 7 lines
Documentation/conf.py +3 -1
@@ -55,7 +55,13 @@ needs_sphinx = '1.7'
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
-              'kernel_abi', 'kernel_feat']
+              'kernel_abi', 'kernel_feat',
+              'sphinx_reredirects',
+]

Besides Jon's comment, if we add something like this, please make such extension optional (in a similar way to what we do for sphinx.ext.imgmath), as this is only pertinent on websites meant to provide the Kernel documentation.

Documentation/conf.py needs_sphinx = '1.7' · line 64

Quoted 4 lines
Documentation/conf.py +4 -0
+
+redirects = {
+     "arch.html": "arch/index.html",
+}

I suspect that maintaining a list of all redirects here can be painful, as, from time to time, we see documentation churns.

We should likely need some script to check what renames happened since a previous Kernel version, generating it automatically.

Again, as this is something that only applies to websites hosting documentation, IMO the best would be to have a separate file ("conf_redirects.py") included on conf.py, that will be auto-generated by a script that would receive, as input, the initial Kernel version where redirects should be preserved.

Regards,
Mauro

Quoted 12 lines
Documentation/conf.py +0 -0
 if major >= 3:
     if (major > 3) or (minor > 0 or patch >= 2):
Documentation/sphinx/requirements.txt +1 -0
index 335b53df35e2..0b067e985edb 100644
@@ -1,3 +1,4 @@
 # jinja2>=3.1 is not compatible with Sphinx<4.0
 jinja2<3.1
 Sphinx==2.4.4
+sphinx_reredirects
maintainer
#6 lore raw
Quoted 5 lines · Mauro Carvalho Chehab

Again, as this is something that only applies to websites hosting documentation, IMO the best would be to have a separate file ("conf_redirects.py") included on conf.py, that will be auto-generated by a script that would receive, as input, the initial Kernel version where redirects should be preserved.

...but again...I think we should observe an actual problem before we start adding any of this. Otherwise we'll just end up carrying a bunch of cruft indefinitely.

jon

#7 lore raw

Em Fri, 28 Apr 2023 07:22:53 -0600
Jonathan Corbet <[email protected]> escreveu:

Quoted 11 lines
Quoted 5 lines · Mauro Carvalho Chehab

Again, as this is something that only applies to websites hosting documentation, IMO the best would be to have a separate file ("conf_redirects.py") included on conf.py, that will be auto-generated by a script that would receive, as input, the initial Kernel version where redirects should be preserved.

...but again...I think we should observe an actual problem before we start adding any of this. Otherwise we'll just end up carrying a bunch of cruft indefinitely.

Agreed. Just saying that, if this is a real problem, a custom conf.py would be the best approach.

Btw, if I'm not mistaken, our building system already allows it via:

make SPHINX_CONF=conf-redirects.py htmldocs

I suspect that it would be possible to add redirects extension and its parameters on it, if someone ever needs it. No need to carry such stuff at the Kernel upstream, as this would very likely limited to some web sites that would be interested on keeping links to old documentation's location.

Regards,
Mauro