Canonical links a.k.a redirection

[marxin]

Let's consider an option like:

:option:`-fmy-option`

The option documentation lives somewhere here:
example.com/foo/bar/baz/a-manual-page.html#cmdoption-fmy-option

My question is if Sphinx can emit redirection for links like example.com/redirect/cmdoption-fmy-option?
Having that, one can then rename any component in foo/bar/baz/a-manual-page.html and the links is gonna be stable.

[astrojuanlu]

@marxin have a look at https://sphinxext-rediraffe.readthedocs.io/, https://documatt.gitlab.io/sphinx-reredirects/, or https://docs.readthedocs.io/en/stable/automatic-redirects.html.

[marxin]

Thank you for the tips. However, I'm not sure any of these can help with the example.com/redirect/cmdoption-fmy-option.
I would need something that can inspect searchindex.js or sphinx.ext.intersphinx's object.inv:

$ python3 -msphinx.ext.intersphinx example.com
...
std:cmdoption
        -Wbuiltin-macro-redefined                gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wbuiltin-macro-redefined
        -Wc++-compat                             gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wc-compat
        -Wc++11-compat                           gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wc-11-compat
        -Wc++11-extensions                       gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wc-11-extensions
        -Wc++14-compat                           gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wc-14-compat

...

[jakobandersen]

@marxin, can you elaborate a bit on the use case?
If an object is moved to a different page then the roles will be resolved to the new location, so I guess your interest is in when another project, B, wants to link to your project, A, via intersphinx? In that case the links can indeed break until the other project recompiles with an updated objects.inv. Is that the case you mean?
Assuming that, I think two parts are needed:

1. A needs to gain this redirect-by-index page.
2. intersphinx during compilation of B should not use the normal URLs, but always link to the redirect page.

For 1 I just tried to make a small prototype at https://github.com/jakobandersen/sphinx_redirect_prototype which uses searchindex.js to lookup IDs and redirect to the right page. However, it looks like that file is created such that objects are indexed by their name, meaning if two domains define the same name (say a Python and a C function called f), then only one is kept.
@tk0miya, do you know if that is intentional? The only place I see the objects part of searchindex.js is being used is at

sphinx/sphinx/themes/basic/static/searchtools.js

Line 331 in 3774c12

for (var name in objects[prefix]) {

, where I don't immediately see why names need to be unique.

For 2, this could be an option in the intersphinx mapping.

[marxin]

@marxin, can you elaborate a bit on the use case?

Sure! First, thank you very much for working on that. Our motivation are console links emitted by the GCC compiler.
Right now, you can see it with:

echo 'int a() {}' | gcc -x c++ -
<stdin>: In function ‘int a()’:
<stdin>:1:10: warning: no return statement in function returning non-void [-Wreturn-type]

Where [-Wreturn-type] points to web documentation of the option: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wreturn-type.

Once we'll switch to Sphinx, I would like to emit https://gcc.gnu.org/onlinedocs/gcc/redirect/cmdoption-Wreturn-type and the redirection script will handle the redirection to a corresponding Sphinx page where -Wreturn-type options is defined. So any intersphinx won't be used.

Am I right, that now, your prototype should be working?

[jakobandersen]

Aha, very cool use case. That basically means you only need a solution to (1). I haven't looked at the prototype after #9649 got merged, but otherwise yes, aside from a bit of cleanup I think it works.
If it works for your case we can try and package it up as an extension for initial use.

[marxin]

Aha, very cool use case. That basically means you only need a solution to (1).

Yes, exactly!

I haven't looked at the prototype after #9649 got merged, but otherwise yes, aside from a bit of cleanup I think it works. If it works for your case we can try and package it up as an extension for initial use.

Please do so, having such an extension would be great!

[marxin]

If it works for your case we can try and package it up as an extension for initial use.

Can you please finish the extension once #9649 was merged?
Thank you very much.

[jakobandersen]

@tk0miya, this redirection feature could be packaged as a third-party extension, but it depends on searchindex.js so for maintenance reasons it would be better to have it in Sphinx it self.
The feature is of general use, similar to the HTML search, in that one can create perma-links with just the ID of an entity, and then later restructure the documentation without breaking the links (assuming the IDs are independent of location).
Would you be against having it in the Sphinx core?

[marxin]

@tk0miya May I please ping this?

[tk0miya]

I'm not sure how many people will use this feature. I feel it will be used by very few people and become a secret feature. I understand it's strongly coupled with the structure of searchindex.js and searchtools.js. But, IMO, it's not enough to bundle it with sphinx-core.

[jakobandersen]

I'm not sure how many people will use this feature. I feel it will be used by very few people and become a secret feature. I understand it's strongly coupled with the structure of searchindex.js and searchtools.js. But, IMO, it's not enough to bundle it with sphinx-core.

In a sense it provides "true" perma-links that will work as long as the entity is contained in the documentation somewhere, even if it gets restructured. So in the future I believe intersphinx resolution should emit these kinds of links.
But I agree that for now it is a more niche feature, so I'll try to make it a non-bundled extension for now.
However, to minimize work I will probably wait for the following two issues to be resolved:

• New searchindex behaviour introduced with 4.3.0 seems to have broken searching #9915
• Drop JavaScript Frameworks #10028

[tk0miya]

I wonder search engines can evaluate the redirects correctly. Almost of crawlers don't support JS. So it's not a good way to adopt it as a default strategy of intersphinx.

[marxin]

However, to minimize work I will probably wait for the following two issues to be resolved:

Makes sense, thanks for working on that.

[marxin]

so I'll try to make it a non-bundled extension for now. However, to minimize work I will probably wait for the following two issues to be resolved:

• New searchindex behaviour introduced with 4.3.0 seems to have broken searching #9915
• Drop JavaScript Frameworks #10028

Apparently, the 2 features are resolved, can you please push the intersphinx extension? Thanks.

[jakobandersen]

Assuming I figured out the packaging stuff correctly, it is now on PyPi: https://pypi.org/project/sphinx-redirect-by-id/.

pip install sphinx-redirect-by-id

[marxin]

Oh, great, thanks a lot!