Stable docs page shows development version

[dstansby]

At https://image.dask.org/en/stable/, there's a non-stable version shown:

I'm guessing this should be a stable version?

[GenevieveBuckley]

This might be because ReadTheDocs expects (like these examples), and the dask-image version tags all start with the letter v.

[GenevieveBuckley]

This might be because ReadTheDocs expects (like these examples), and the dask-image version tags all start with the letter v.

This can probably be solved by using a custom match in the automation rules for ReadTheDocs.

@jakirkham will probably have to do this: it looks like you have to log in to ReadTheDocs to both (1) set automation rules, and (2) activate any tags ReadTheDocs has not previously identified as a version tag.

I tried logging in to ReadtheDocs with github, but I don't see anything related to dask-image linked to my account.

[GenevieveBuckley]

Separate to this discussion, the main docs page at https://image.dask.org does redirect to https://image.dask.org/en/latest/ (not stable). That is deliberate, from my understanding (mostly because we often have a delay between a new feature going in and an official release being made. It seems better if people know a new thing exists rather than not know)

[jakirkham]

I tried logging in to ReadtheDocs with github, but I don't see anything related to dask-image linked to my account.

@GenevieveBuckley What is your handle on RTD?

@m-albert would you like access to RTD as well? If so, what is your handle?

[GenevieveBuckley]

@GenevieveBuckley What is your handle on RTD?

It's GenevieveBuckley
That's what I see in the top right hand corner with the account name, and it makes sense to me that if I've logged in via Github then they'd both be the same.

[jakirkham]

Added. They say there is some kind of invitation that you need to accept. Guessing in email

[jakirkham]

Also started a new build for the latest tag. Guessing this will fix this issue

[jakirkham]

Ok that wasn't enough. Think we also need to change this logic to reflect setuptools-scm

dask-image/docs/conf.py

Line 19 in d3c944f

import dask_image._version

dask-image/docs/conf.py

Lines 66 to 73 in d3c944f

	# The version info for the project you're documenting, acts as replacement
	# for |version| and |release|, also used in various other places throughout
	# the built documents.
	#
	# The full version, including alpha/beta/rc tags.
	release = dask_image._version.__version__
	# The short X.Y.Z version.
	version = '.'.join(release.split('.')[:3])

[jakirkham]

Interesting it looks like both of these tags are on the same commit. Is that expected?

[jakirkham]

Looks like there was a new build with the 2024.5.1 tag added recently

Does this fix it?

[jakirkham]

Interesting this shows the right tag at the bottom in RTD. However the rendered docs look off

Maybe there is a setuptools-scm setting we are missing?

[m-albert]

@m-albert would you like access to RTD as well? If so, what is your handle?

Thanks @jakirkham! My handle on readthedocs is "m-albert" (also over github)

[GenevieveBuckley]

Interesting it looks like both of these tags are on the same commit. Is that expected?

That is what I did.
Although I wasn't really thinking about which commit tags were being attached to, I just tried to make a release candidate version, then realised conda-forge would only build for real releases, and made another tag for that. I mostly just wanted to trigger the release deployment. If it's causing a problem, maybe we can get rid of the the rc1 tag somehow (no one will care about that)

[GenevieveBuckley]

I found the problem!
The default html_title parameter in the docs/conf.py is using the full release name, not the shorter release version. That's what's getting passed into the dask sphinx template and being displayed in the top left corner.

https://github.com/dask/dask-image/blob/main/docs/conf.py#L131-L133

Hang on a sec, I'll make a fix...

[jakirkham]

@m-albert would you like access to RTD as well? If so, what is your handle?

Thanks @jakirkham! My handle on readthedocs is "m-albert" (also over github)

Added. Please look for an invite (likely in email)

[jakirkham]

To the issue at hand, was looking at RTD's own documentation and spotted this recommendation

Namely RTD changes some files in the repo as part of their build process. The result is the repo appears dirty to git (as there are unstated changes to tracked files). They recommended telling git in the RTD build process to ignore these changed files

Included these changes in PR ( #378 ) along with a test in RTD to ensure the repo is clean. Also tagged as 2024.5.3. Looking at the RTD build, this appears to do the right thing