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.


Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>
---
 Documentation/conf.py                 | 8 +++++++-
 Documentation/sphinx/requirements.txt | 1 +
 2 files changed, 8 insertions(+), 1 deletion(-)
  

Costa Shulyupin <costa.shul@redhat.com> writes:

> 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 <costa.shul@redhat.com>
> ---
>  Documentation/conf.py                 | 8 +++++++-
>  Documentation/sphinx/requirements.txt | 1 +
>  2 files changed, 8 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 37314afd1ac8..514bfe6a8166 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -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",
> +}

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
  

Costa Shulyupin <costa.shul@redhat.com> writes:

> 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
  

> is there an actual problem needing to be solved here?

There is not an actual problem. Only a potential.

Thanks,
Costa
  

Em Thu, 27 Apr 2023 13:12:39 +0300
Costa Shulyupin <costa.shul@redhat.com> escreveu:

> 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 <costa.shul@redhat.com>
> ---
>  Documentation/conf.py                 | 8 +++++++-
>  Documentation/sphinx/requirements.txt | 1 +
>  2 files changed, 8 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 37314afd1ac8..514bfe6a8166 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -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.

> +
> +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

>  
>  if major >= 3:
>      if (major > 3) or (minor > 0 or patch >= 2):
> diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
> index 335b53df35e2..0b067e985edb 100644
> --- a/Documentation/sphinx/requirements.txt
> +++ b/Documentation/sphinx/requirements.txt
> @@ -1,3 +1,4 @@
>  # jinja2>=3.1 is not compatible with Sphinx<4.0
>  jinja2<3.1
>  Sphinx==2.4.4
> +sphinx_reredirects
  

Mauro Carvalho Chehab <mchehab@kernel.org> writes:

> 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
  

Em Fri, 28 Apr 2023 07:22:53 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab@kernel.org> writes:
> 
> > 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