Iris: Which version is stable?

[rcomer]

📚 Documentation

If I look at the docs for our "stable" version, I can't see anything that tells me this is (currently) Iris v3.0.1:
https://scitools-iris.readthedocs.io/en/stable/

Constrast this with, say, numpy, where it's really obvious that the stable version is v1.20.
https://numpy.org/doc/stable/

Could we add something to the side bar to show the exact version? It might also be good to add something to the "latest" docs to indicate that this is for the unreleased version - Matplotlib does this with a big red stripe across the top:
https://matplotlib.org/devdocs/index.html

[tkknight]

Interesting observation @rcomer. You are correct in that stable does not explicitly state what version it is. We are now using the standard approach to implemtnatin Read the Docs in that:

• latest = master (unreleased)
• stable = more recent release (v3.0.1 atm)
• list of all versions (just v3.0.0 at, as earlier versions are not read the docs compatible, see legacy link on the main docs page and sidebar)

This can be seen by clicking on the green text of the current version that is being viewed, see pic:

I agree that it would be an improvement for:

• latest to have a clear notice/banner that says is it unreleased code (like the example you gave)
• stable to also show the version it is actually using (can be inferred by the image above but is perhaps not intuitive enough.

An issue that I thinks covers the second bullet point is already on the readthedocs github project, see https://github.com/readthedocs/readthedocs.org/issues/4529

I have learnt a lot about how read the docs works in getting the Iris Docs revitalised so I will dwell on how to best approach this - I would like an elegant automated solution that needs no further changes upon new releases of Iris.

[tkknight]

Banner for the latest (unreleased) documentation now merged to master. See #3999.

Next up will think about options to improve the version awareness of stable.

[tkknight]

Ref: Stable version to be clear

A few options to achieve this:

Option 1

Adopt the numpy (https://numpy.org/doc/stable/) approach, where the main landing page (index) states the
version number on the title. For Iris this means on https://scitools-iris.readthedocs.io/en/latest/index.html instead of Iris Documentation it could be Irs v3.0.1.

• Pro: Easy
• Cons: Only shown on the index page (just like numpy)

Option 2

Use templating to add the version explicitly to the read the docs version in the top left corner under the logo. This is achievable. The logic could check for stable and then add (v3.0.1) after it.

(mockup)

• Pro: visible on all pages in the docs as it will be in the sidebar
• Cons: It uses a template block header of sidebartitle (see template) and we need to add an if condition after line 145. However, my understanding is that for template blocks we can either replace the content fully, or add our content before or after the block. In this case we would need to copy the the entire block into our template and then edit. This would be a visually good solution but does not feel elegant, especially if the sphinx_rtd_theme were to update this section we would not see the change.

Option 3

The logo at the top left corner of the docs is currently a png file, created from the svg file. The svg file was not used when the docs were moved to Read the Docs (iris 3) as it would not render correctly in a web browser (would trim the right side). However as an svg file is essentially text we could use templating to substitute a version number within the image.

(mock up)

• Pros: Visible on all pages in the docs. Not replacing any sphinx_rtd_theme template blocks completely
• Cons: Need to improve the svg to ensure sizing and alignment works for a varied length version number. Also makes the sphinx-build a little more complicated, possibly even a sphinx extension needed.

Note that https://matplotlib.org/devdocs/index.html uses a similar approach to Option 2 but visually looks like Option 3. In that is uses (a lot) of custom templating) and then a html div to insert the version number on top of an image (I think).

Option 4

Use templating (like option 2) but focus on the breadcrumbs at the top of the page. For example: "(house icon) » Contributing to the Code Base » Testing » Running the Tests" would instead be "(house icon) Iris v3.0.1 » Contributing to the Code Base » Testing » Running the Tests"

• Pros: Visible on all pages in the docs. Much smaller block that is being replaced
• Cons: Still uses a complete override for a block (albeit a small one)

Brain dump over - comments welcome, particularly if you have a more elegant idea.

[trexfeathers]

The logo at the top left corner of the docs is currently a png file, created from the svg file. The svg file was not used when the docs were moved to Read the Docs (iris 3) as it would not render correctly in a web browser (would trim the right side). However as an svg file is essentially text we could use templating to substitute a version number within the image.

Cons: Need to improve the svg to ensure sizing and alignment works for a varied length version number. Also makes the sphinx-build a little more complicated, possibly even a sphinx extension needed.

I have tested my own SVG for RTD rendering and it seems to be fine. That SVG is proposed in SciTools/marketing#1, but I have been waiting for some time for @abooton to review it as agreed offline. The programmatic generation may also be helpful in solving the Cons you referenced above, although the exact nature of how this would be integrated into Iris is up for debate (see #3935 for a fully automated example).

Unfortunately I can only undertake further work on this in my spare time at the moment.

[trexfeathers]

From a user standpoint I think the best is Option 2, even if it is a minor headache for us. Is there perhaps a sphinx extension that could help us out?

[rcomer]

Wow, thanks for digging into this @tkknight, it’s rather more complicated than I could have imagined!

[rcomer]

I definitely like the idea of having it in the sidebar (options 2 or 3). As well as being visible on every page, it’s consistent with where the number appears for all the other released pages. So more intuitive for the user to find.

I have no opinions from the development point of view...

[bjlittle]

IMHO the best choice is option 2.

However, rtd aren't making this easy, but there is community discussion about making this customisable.

We could actually do this, and @tkknight has demonstrated that this is possible, but technically it puts us in a difficult and risky position as we could just break the documentation due to changes within the rtd infra-structure. So for me, at present it's a non-option option :stuck_out_tongue_winking_eye:

I'd like to hold out for option 2... but we can't hold our breath; it requires a rtd change and that may not happen.

The cheap win is option 1. Let's go for that, and perhaps once we've sorted out the final logo (nudge @abooton :wink: ) then option 3 will be achievable and on the table.

Also let's keep our eye on any movement from rtd, and perhaps ultimately option 2 will land in our lap... one day :pray:

Does this sound reasonable guys?

If so, action option 1 and close this issue :+1:

@tkknight Between ourselves we can monitor the rtd situation for option 2 ? How did you want to do that? A new separate documentation tech debt issue that cross-references this one perhaps?

[tkknight]

@thanks for input @bjlittle. I agree with you, if only to minimise the amount of customisation we are using for the standard rtd theme.

I can do a small PR for Option 1. Yes, a separate tech debt issue would cover it.

@rcomer, you raised this issue, happy with this approach?

[rcomer]

Thanks all! Yes this makes sense to me.

[tkknight]

PR #4030 to implement option 1.

[tkknight]

Tech Debt issue created. See #4031