Rtd

[jburel]

Following the IT problems, this PR migrates the documentation to readthedocs.

see https://jburel-ome-documentation.readthedocs.io/en/latest/

The Javadoc, slice doc migration is not considered in this PR

cc @joshmoore @sbesson

[sbesson]

From my side, similar support and questions as the ones raised in ome/bio-formats-documentation#196:

• I assume the documentation home page would become https://omero.readthedocs.io/?
• when would the switch happen? is this something we want to do immediately or wait until the next OMERO release?
• is there a list of actions to be performed after merging (redirects, website updates)? Should this be captured as an issue/checklist?

[joshmoore]

• I assume the documentation home page would become https://omero.readthedocs.io/?

this makes me wonder again if we shouldn't rename https://github.com/ome/openmicroscopy to match "omero-documentation"

[joshmoore]

This is due to a limitation in sphinx not being able to build more than a subdirectory? Bit confused.

[jburel]

From my side, similar support and questions as the ones raised in ome/bio-formats-documentation#196:

• I assume the documentation home page would become https://omero.readthedocs.io/?

That's the name I was thinking but we can pick the name we wish

• when would the switch happen? is this something we want to do immediately or wait until the next OMERO release?
  We have a few doc improvement that could be released outside omero. Also recent releases of OMERO.web contain new configuration fields that are not available in the documentation.
• is there a list of actions to be performed after merging (redirects, website updates)? Should this be captured as an issue/checklist?
  I can start an issue with checklist if we are all on board. Redirects will be needed
  The main question is we are happy to have a version tag not necessarily matching the omero/openmicroscopy tag cf. point 2

[sbesson]

We have a few doc improvement that could be released outside omero. Also recent releases of OMERO.web contain new configuration fields that are not available in the documentation.

So you would vote for making this live and starting to publish asap?

I can start an issue with checklist if we are all on board. Redirects will be needed

👍 from my side for capturing this

The main question is we are happy to have a version tag not necessarily matching the omero/openmicroscopy tag cf. point 2

While in the case of Bio-Formats, most of the components and the documentation are typically released in sync (which is possibly why we are unsure about decoupling the tag numbers), we have long passed this stage for the OMERO documentation. https://docs.openmicroscopy.org/omero/5.6.3/ tells OMERO 5.6.3 Documentation which is the version of the binaries built in ome/openmicroscopy but internally for instance OMERO.py is at 5.10.1 and more significantly OMERO.web which has its own documentation section is at 5.12.0.

Decoupling the tag from the binary does not seem to make a huge difference to me although we might need to review the internal versions. A possibility would be track the server/web version numbers and use them appropriately i.e. refer to OMERO.server 5.6.3 and OMERO.web 5.12.0

That's the name I was thinking but we can pick the name we wish

Thinking of the discussion above, it looks like the current common denominator is that this constitutes the reference documentation for the OMERO 5 ecosystem. Another possibility would be https://omero5.readthedocs.io/. Likely harder to find but it would allow e.g. to clearly separate documentation sets between OMERO 5 and a future breaking version.

this makes me wonder again if we shouldn't rename https://github.com/ome/openmicroscopy to match "omero-documentation"

Definitely feel like the last (but hardest) thing to unify. A fewnames coming to mind ome/omero, ome/omero-binaries, ome/omero-dist (all of this with their s/omero/omero5 variants depending on how we feel about the above.

[jburel]

Re-activating this branch following the release. Migrating to rtd will simplify the release of the doc.

[sbesson]

In the same spirit as ome/ome-zarr-py#121, should we create a reathedocs project and activate per-PR build so that we can review this in the checks?

[jburel]

I have tested on my account see https://jburel-ome-documentation.readthedocs.io/en/latest/ and restarted the build

[sbesson]

While I would have expected the content to be equivalent to https://docs.openmicroscopy.org/omero/5.6.4, the link above still displays OMERO 5.6.3 documentation?

[jburel]

I think it is due to the settings I put a while back, when checking stable vs latest etc.
I will need to look into it again

[jburel]

The reason it was 5.6.3 is b/c I set at the time an environment variable in rtd (see https://readthedocs.org/dashboard/jburel-ome-documentation/environmentvariables/) to test and be compatible with the current build system. I did not change it before building. It is now at 5.6.4
This strategy needs to be reviewed. We will forget about it with the new setup. Version should be set in conf.py as we do for code i.e. 5.6.5-SNAPSHOT and drop SNAPSHOT before tagging

[sbesson]

Is the last commit deployed?

[jburel]

it has

[sbesson]

Excluding the question around the versioning/lifecycle above which can be captured as a next to do, the staging readthedocs deployment looks good to me. Overall, the migration proposed here makes sense to me, builds on top of an established platform used by many projects (https://readthedocs.org/sustainability/) and aims to address several issues that have been arising over the last few years:

• occasional outage of the UoD infrastructure leading to the OMERO documentation becomingunavailable for the community
• ability to release documentation fixes independently of a corresponding OMERO.server release

As always, these benefits come at the cost of a different workflow both in terms of review and release processes.

The primary question is whether the rest of the @ome/omero team is comfortable with this approach:

• any comments/objections/amendments to this proposal?
• are there outstanding blockers or questions that we would need to discuss?
• assuming we move forward, should this be merged and deployed and next steps captured as issues?

[jburel]

The versions have been decoupled in this PR, the updated doc is now available.

[jburel]

I have all the changes that I wanted to do for that round.
I will list it for discussion on Monday.

[jburel]

Note that this PR does not address the hosting of documentation like https://docs.openmicroscopy.org/omero-model/5.6.5/javadoc/

[will-moore]

I'm seeing a couple of different versions 5.6.5-SNAPSHOT (heading) vv 5.6.4 (in the text) just now:

[jburel]

Yes: the doc and the code have been decoupled i.e. the doc version is 5.6.5-SNAPSHOT and the server version is 5.6.4
We need to use 2 different variables

[joshmoore]

• I assume the documentation home page would become https://omero.readthedocs.io/?

Going back to this, 👍 for this initially but I could also see that becoming a landing page (like https://omero-guides.readthedocs.io/) on top of omero-server, omero-web, etc.

[jburel]

Thanks for the suggestion, better to use omero-guides from the start in that case

[joshmoore]

I don't think so. Or at least, not as guides are currently constructed. This gets back to the four types of documentation. Again, I don't think there would be a problem having a page that points to all four types, but there are definitely different user flows and I certainly would suggest right now that we should get rid of the flows we have without planning/designing.

[sbesson]

I'm seeing a couple of different versions 5.6.5-SNAPSHOT (heading) vv 5.6.4 (in the text) just now:

Maybe this raises the question of whether the documentation version should be exposed in the generated documentation or only remains internal to reduce the confusion.

[will-moore]

Docs look good :)

[joshmoore]

Maybe this raises the question of whether the documentation version should be exposed in the generated documentation or only remains internal to reduce the confusion.

I could see using "5.6" since that's relevant for compatibility. Moving forward, maybe just "OMERO 6", but that might be something we consider when it comes to the RTD URLs.

[sbesson]

Going back to this, 👍 for this initially but I could also see that becoming a landing page (like https://omero-guides.readthedocs.io/) on top of omero-server, omero-web, etc.

And semi-related, assuming the current content gets published under e.g. https://omero.readthedocs.io/, do we believe we could easily redirect all the URLs if part of the content was split into its own reference documentation at a later stage?

In general, from the thread, there are several open questions/actions that will need to be tackled post-merging of this PR including redirection from docs.openmicroscopy.org, CI, configuration etc. @jburel do you have a reference place to capture these?

[jburel]

See #2198 for actions

[jburel]

@will-moore 9d76168 now uses the major/minor version so that will avoid confusion

[jburel]

Going back to this, 👍 for this initially but I could also see that becoming a landing page (like https://omero-guides.readthedocs.io/) on top of omero-server, omero-web, etc.

And semi-related, assuming the current content gets published under e.g. https://omero.readthedocs.io/, do we believe we could easily redirect all the URLs if part of the content was split into its own reference documentation at a later stage?

I think so, it will be similar to the redirect we have already

In general, from the thread, there are several open questions/actions that will need to be tackled post-merging of this PR including redirection from docs.openmicroscopy.org, CI, configuration etc. @jburel do you have a reference place to capture these?

See #2198 for actions

[jburel]

Merging as discussed yesterday and preparing https://omero.readthedocs.io/