docs: redirect from old arch to the new one
Subsystems (2)
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
@@ -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
@@ -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
Jonathan Corbet
maintainerQuoted 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.
Signed-off-by Costa Shulyupin <[email protected]>--- Documentation/conf.py | 8 +++++++- Documentation/sphinx/requirements.txt | 1 + 2 files changed, 8 insertions(+), 1 deletion(-)Documentation/conf.py +0
-0@@ -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
Jonathan Corbet
maintainerQuoted 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
Quoted 1 line
is there an actual problem needing to be solved here?
There is not an actual problem. Only a potential.
Thanks,
Costa
Mauro Carvalho Chehab
maintainerEm 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.
Signed-off-by Costa Shulyupin <[email protected]>--- Documentation/conf.py | 8 +++++++- Documentation/sphinx/requirements.txt | 1 + 2 files changed, 8 insertions(+), 1 deletion(-)Documentation/conf.py +0
-0
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
-0if major >= 3: if (major > 3) or (minor > 0 or patch >= 2):Documentation/sphinx/requirements.txt +1
-0@@ -1,3 +1,4 @@ # jinja2>=3.1 is not compatible with Sphinx<4.0 jinja2<3.1 Sphinx==2.4.4 +sphinx_reredirects
Jonathan Corbet
maintainerQuoted 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 onconf.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
Mauro Carvalho Chehab
maintainerEm 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 onconf.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