Migration to RTD

[jburel]

List of tasks for the migration to RTD

• Convert infrastructure to work with rtd See Rtd #2195
• Review version number since doc and openmicroscopy release will no longer match
• Select name on rtd i.e. https://omero.readthedocs.io. This will be final see Migration to RTD #2198 (comment)
• Redirect
  • https://docs.openmicroscopy.org/omero/latest to https://omero.readthedocs.io/en/stable/ i.e. latest -> stable
  • https://docs.openmicroscopy.org/omero/5 to https://omero.readthedocs.io/en/stable/.
• Check change of name on rtd. See Migration to RTD #2198 (comment)
• Automatic synchronisation with upstream repositories. See GHA update #2197
• Configure readthedocs
• Adjust CI to build doc

[jburel]

Source https://docs.readthedocs.io/en/stable/faq.html

How do I change my project slug (the URL your docs are served at)?¶
We don’t support allowing folks to change the slug for their project. You can update the name which is shown on the site, but not the actual URL that documentation is served.

The main reason for this is that all existing URLs to the content will break. You can delete and re-create the project with the proper name to get a new slug, but you really shouldn’t do this if you have existing inbound links, as it breaks the internet.

If that isn’t enough, you can request the change sending an email to [email protected].

How do I change the version slug of my project?¶
We don’t support allowing folks to change the slug for their versions. But you can rename the branch/tag to achieve this. If that isn’t enough, you can request the change sending an email to [email protected].

[jburel]

• https://omero.readthedocs.io/en/latest/ corresponds to the develop and the version is hidden See https://dev.readthedocs.io/en/latest/design/privacy-levels.html
• https://omero.readthedocs.io/en/stable corresponds to the tag. This is the equivalent to https://docs.openmicroscopy.org/omero/latest

[pwalczysko]

• https://omero.readthedocs.io/en/latest/ corresponds to the develop and the version is hidden See https://dev.readthedocs.io/en/latest/design/privacy-levels.html

  • https://omero.readthedocs.io/en/stable corresponds to the tag. This is the equivalent to https://docs.openmicroscopy.org/omero/latest when

Looks very nice !

[jburel]

I have added a rule so a dedicated version is automatically built when a tag is pushed
see for example https://omero.readthedocs.io/en/v5.6.4-2/

[sbesson]

Is the plan to enable rtd on pull requests (similar to the guides for instance)? If so, does this make https://github.com/ome/omero-documentation/blob/develop/.github/workflows/sphinx.yml effectively redundant ?

[jburel]

It should be enabled on pull requests, so yes the job will be redundant

[jburel]

Redirect options

• https://docs.openmicroscopy.org/omero/latest -> https://omero.readthedocs.io/en/stable/
• https://docs.openmicroscopy.org/omero/5.6.x/ -> https://omero.readthedocs.io/en/v5.6.x/
• https://docs.openmicroscopy.org/omero/5 -> https://omero.readthedocs.io/en/stable/ (preferred) or https://omero.readthedocs.io/en/v5.6.x/ The second option means that each time we push a tag, the redirect will need to be updated
• https://docs.openmicroscopy.org/omero/5..6 -> https://omero.readthedocs.io/en/stable/ (preferred) or https://omero.readthedocs.io/en/v5.6.x/ The second option means that each time we push a tag, the redirect will need to be updated

As discussed asynch in slack, until we switch to 6,

• https://docs.openmicroscopy.org/omero/5 -> https://omero.readthedocs.io/en/stable/
  seems the most suitable option
  When we switch we change it to https://docs.openmicroscopy.org/omero/5 -> https://omero.readthedocs.io/en/v5.6.x/

[sbesson]

From a quick look, .htaccess seem to do the job for redirecting /omero/XXX URLs to another domain including deep link redirects.

A few questions:

https://docs.openmicroscopy.org/omero/5.6.x/ -> https://omero.readthedocs.io/en/v5.6.x/

For instance, we already published https://omero.readthedocs.io/en/v5.6.5-1/ with minor modifications. Does this mean this link will need to keep evolving every time we make a rtd release?

https://docs.openmicroscopy.org/omero/latest -> https://omero.readthedocs.io/en/stable/
https://docs.openmicroscopy.org/omero/5 -> https://omero.readthedocs.io/en/stable/ or https://omero.readthedocs.io/en/v5.6.x/

What about retaining the existing logic and have
https://docs.openmicroscopy.org/omero/latest -> https://docs.openmicroscopy.org/omero/5.6.5 -> https://omero.readthedocs.io/en/v5.6.x/ ?

I assume some links will need to be updated on every OMERO.server release anyways?

[jburel]

https://docs.openmicroscopy.org/omero/latest -> https://docs.openmicroscopy.org/omero/5.6.5 -> https://omero.readthedocs.io/en/v5.6.x/ ?

that means that https://docs.openmicroscopy.org/omero/latest will rarely point to https://omero.readthedocs.io/en/stable/
i.e. each time we do a doc update we will need to update the redirect

The easiest option is to point https://docs.openmicroscopy.org/omero/latest, https://docs.openmicroscopy.org/omero/5 and https://docs.openmicroscopy.org/omero/5.6 to https://omero.readthedocs.io/en/stable/

and https://docs.openmicroscopy.org/omero/5.6.5 to https://omero.readthedocs.io/en/v5.6.5/ in case someone wants a specific tag

[sbesson]

i.e. each time we do a doc update we will need to update the redirect

So you would not update https://docs.openmicroscopy.org/omero/5.6.5 when a new 5.6.5-z tag is pushed to this repository either ? That's the least amount of maintenance but we need to be comfortable with the fact that our redirects might point to outdated readthedocs versions.

[sbesson]

Also sharing the configuration for the redirection which is pretty simple

[sbesson@idr0-slot3 5.6.5]$ cat .htaccess 
Redirect 301 /omero/5.6.5 https://omero.readthedocs.io/en/v5.6.5-1/

[jburel]

i.e. each time we do a doc update we will need to update the redirect

So you would not update https://docs.openmicroscopy.org/omero/5.6.5 when a new 5.6.5-z tag is pushed to this repository either ? That's the least amount of maintenance but we need to be comfortable with the fact that our redirects might point to outdated readthedocs versions.

There's a banner indicating that there's a new version of you are looking at the most recent tag for example go to v5.6.5 so I don't think it will be a problem

[sbesson]

The proposal from #2198 (comment) is now implemented and should redirect both the top-level and the deep links

[sbesson@idr0-slot3 omero]$ cat 5.6.5/.htaccess 
Redirect 301 /omero/5.6.5 https://omero.readthedocs.io/en/v5.6.5/
[sbesson@idr0-slot3 omero]$ cat 5.6/.htaccess 
Redirect 301 /omero/5.6 https://omero.readthedocs.io/en/stable/
[sbesson@idr0-slot3 omero]$ cat 5/.htaccess 
Redirect 301 /omero/5 https://omero.readthedocs.io/en/stable/
[sbesson@idr0-slot3 omero]$ cat latest/.htaccess 
Redirect 301 /omero/latest https://omero.readthedocs.io/en/stable/

No immediate objection to moving with this approach and possibly revisiting later but I'll leave others who have been updating the technical documentation to review /cc @joshmoore @pwalczysko

[sbesson]

Another issue I noticed while posting the URLs to the documentation is that the documentation title currently reads as

OMERO Documentation version 5.6 - OMERO 5.6.5-SNAPSHOT-1 documentation

I assume this comes from

omero-documentation/omero/conf.py

Line 40 in 36cced7

version = "5.6.5-SNAPSHOT-1"

. Are we still expecting to manage this version by hand in addition to the tag?

[jburel]

I think we should try to automate that.
I will check

[jburel]

I have made the release process section more visible see #2260

[jburel]

Explanation of one cancelled job when the tag is pushed readthedocs/readthedocs.org#8015 (comment)

[sbesson]

Assuming this can be closed?