Question: How to redirect from old branch to new branch documentation at ReadTheDocs?

[fgalan]

(This issue comes from http://stackoverflow.com/questions/39882805/how-to-redirect-from-old-branch-to-new-branch-documentation-at-readthedocs, so I haven't just copy-pasted instead of using the suggested issue template. I hope this would be also acceptable).

We are rendering ReadTheDocs (RTD) documentation for a software project hosted at github (in particular, this one).

Recently we have changed our main branch due to internal policies. In the past we used "develop" as main branch. Now, we are unsing "master" as default branch. The "develop" branch is still in our repository, but it is not receiving new contributions (at the end, it will be deleted).

The problem is that all the links to documentation (that we have been distributing among our users during years) like this one https://fiware-orion.readthedocs.io/en/develop/user/walkthrough_apiv2/index.html will point to an obsolete piece of documentation, as now the right one is https://fiware-orion.readthedocs.io/en/master/user/walkthrough_apiv2/index.html

Does RTD have some functionality (redirect, alias, etc.) that could solve this problem? As far as I checked, RTD supports several redirection types ("Prefix redirect", "Page redirect", etc.) but after looking them all it seems they cannot do this kind of redirection (or I haven't understood how the work to do it :). I mean redirecting

https://fiware-orion.readthedocs.io/$lang/develop/path/to/something.html

to

https://fiware-orion.readthedocs.io/$lang/master/path/to/something.html

Any idea about how to solve this problem or feasible workarounds will be highly appreciated.

[barbara-sfx]

I think this answers your question. I believe you would use

From /develop/ To /master/

http://docs.readthedocs.io/en/latest/user-defined-redirects.html#prefix-redirects

[fgalan]

Thank you very much for the answers.

I'm trying to configure such /develop/ to /master/ redirect using the prefix redirect functionality you mention. However, I'm not able to configure the destination so the outcome is

Outcome: /develop/faq.html -> /$lang/$version/faq.html

and not the one that I'd need:

Outcome: /develop/faq.html -> /master/faq.html

See attached screenshot:

[fgalan]

Another attemp, this time adding $lang. Outcome now shows:

Outcome: /$lang/develop/faq.html -> /$lang/$version/faq.html

but what I need would be:

Outcome: /$lang/develop/faq.html -> /$lang/master/faq.html

Screenshot:

[shimizukawa]

+1 to redirecting old-branch to new-branch

[tk0miya]

+1

[barbara-sfx]

@fgalan I think you want to go into the Versions setting and change develop (which is what I imagine is there now) to master. In our case, $version = latest

[fgalan]

A long time has passed since I needed this (October 2016). I'm not sure, but I don't remember that Versions settings that time. Has it been introduced recently (in the Octuber 2016 to now timeframe)?

[barbara-sfx]

Well, it's there now, so either it was there and you didn't know it, or it has in fact been added since then. I don't know which.

[wohali]

We also want the ability to specify redirects of the form /$lang/#.#.# to /$lang/#.#.#, or even /$lang/#.#.# -> /$lang/stable, so that people looking for obsolete versions of the documentation get auto-redirected to the current or a specified supported old version.

[barbara-sfx]

@wohali My guess is that is what prefix redirect is supposed to do, but I just reported that it only has From and not To, so I'm actually not sure how it is supposed to work.

[stsewd]

@barbara-sfx please see https://docs.readthedocs.io/en/latest/user-defined-redirects.html

[barbara-sfx]

Ah, looks like prefix redirect ONLY redirects to latest version (per response from support, which led me to this doc):

https://docs.readthedocs.io/en/latest/user-defined-redirects.html

I responded: Thanks, that helps. But it would be even better if I could specify where I wanted to redirect to. e.g. Maybe I have /rev4/ and want to redirect to /rev5/ . Can you add this as a feature request?

[barbara-sfx]

Thanks, that helps. But it would be even better if I could specify where I wanted to redirect to. e.g. Maybe I have /rev4/ and want to redirect to /rev5/ . Can you add this as a feature request?

…

-- Barbara P.S. I also suggest you add a link to that document on the redirects page.

On Aug 9, 2018, at 10:01 AM, Santos Gallegos ***@***.*** ***@***.***>> wrote: @barbara-sfx <https://github.com/barbara-sfx> please see https://docs.readthedocs.io/en/latest/user-defined-redirects.html <https://docs.readthedocs.io/en/latest/user-defined-redirects.html> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2444 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AQ457lfSkenB7_JajTOXHgtAIxip63V8ks5uPGrjgaJpZM4KSUXC>.

[humitos]

I think this is a bug on our side.

First of all, our UX says that a Prefix Redirect will match the Absolute path, but taking a look at the code it only consider the path as everything that comes after the language and version:

https://github.com/rtfd/readthedocs.org/blob/5d8becd51bc9272511ebd86262a3be5e00c7e851/readthedocs/redirects/models.py#L128

So, for example, if the URL is /en/2.0/guides/somepage.html the path used to the prefix match is only the /guides/somepage.html.

This transformation is done at this function:

https://github.com/rtfd/readthedocs.org/blob/5d8becd51bc9272511ebd86262a3be5e00c7e851/readthedocs/redirects/utils.py#L56-L66

Example:

In [25]: path = '/en/2.0/guides/something.html'

In [26]: language, version_slug, path = language_and_version_from_path(path)

In [27]: path
Out[27]: '/guides/something.html'

I hope to propose a solution for this soon. Marking as a bug.

[humitos]

Hi all! This was deployed yesterday and should be working properly. You may want to create the redirects you weren't able to do it.

Please, if you find any other issue open a new one :)