readthedocs stable build is out of date

[stscijgbot-jp]

Issue JP-3549 was created on JIRA by Melanie Clarke:

It looks like the stable build for the pipeline readthedocs has not been updated in some time:

https://jwst-pipeline.readthedocs.io/en/stable](https://jwst-pipeline.readthedocs.io/en/stable/jwst/pipeline/calwebb_spec2.html)

is documentation for jwst v1.8.4, last built November 2022

[stscijgbot-jp]

Comment by Howard Bushouse on JIRA:

Zach Burnett Brett Graham Joe Hunkeler Could you check on this please. I believe that updating the "stable" docs via a copy of "latest" whenever we do a build release was supposed to be part of the release procedure (maybe not). Anyway, we'll need to get "stable" updated from jwst 1.13.4 within the next week or so, when that version goes into use in Operations.

[stscijgbot-jp]

Comment by Brett Graham on JIRA:

I think the "stable" version is built from:
https://github.com/spacetelescope/jwst/tree/stable
which hasn't been updated since 1.9.6 (based on the most recent commit message).
The release wiki page is a bit vague on when this branch should be updated:
https://github.com/spacetelescope/jwst/wiki/Release-Procedures#⁠5-maintain-the-stable-branch-if-necessary
Some clarification there might help to keep it up-to-date (specifically when is it necessary/not-necessary to update the branch?).

[stscijgbot-jp]

Comment by Joe Hunkeler on JIRA:

I've updated the stable branch from 1.9.6 to 1.13.4. If you want me to drop it back down to 1.13.3, I can.

 

As far the wiki docs are concerned, which of these sounds like the best approach?

 

1. Update "stable" to point to the LATEST public release tag (immediately at release-time)

2. Update "stable" to point to the tag DMS runs on their servers (in this case it should become a standalone procedure due to long periods of "we haven't installed anything yet")

3. Update "stable" to point to the PREVIOUS public release tag (it already went through the gauntlet in production after all)

[stscijgbot-jp]

Comment by Howard Bushouse on JIRA:

When I go to the "stable" version on the web it claims to be version "(1.13.5.dev0+g88dfde9.d20240226)". Is that expected? Shouldn't it just be plain ol' "1.13.4"?

That dev version sounds like it maybe came from the jwst/master branch, as opposed to coming from the 1.13.4 tag.

[stscijgbot-jp]

Comment by Howard Bushouse on JIRA:

Joe Hunkeler Option 1 sounds fine to me. As soon as we make a release tag, it presumably means that the code is publicly available on pypi and hence it seems fine to then have "stable" be tied to that release, regardless of whether or not it's been installed into DMS operations yet.

[stscijgbot-jp]

Comment by Joe Hunkeler on JIRA:

$ git log --oneline --decorate -n1 upstream/stable
88dfde99f (HEAD -> stable, tag: 1.13.4, upstream/stable, upstream/release/1.13.x, origin/stable, release/1.13.x) metadata for `1.13.4` (#8222)

No, I wasn't expecting it to generate a dev version string. The stable branch is aligned with the 1.13.4 tag.

[stscijgbot-jp]

Comment by Joe Hunkeler on JIRA:

I tried forcing RTD to "unshallow" the repository after checkout and it didn't do anything useful either. The 1.13.4 tag is present according the build log (in shallow and unshallow modes), but somehow the commit isn't associated with it. I'll keep poking around.

[stscijgbot-jp]

Comment by Joe Hunkeler on JIRA:

 

mkdir /tmp/jwst_docs
cd /tmp/jwst_docs
git clone --depth 1 https://github.com/spacetelescope/jwst .
git fetch origin --force --prune --prune-tags --depth 50 refs/heads/stable:refs/remotes/origin/stable
git checkout --force origin/stable
git clean -d -f -f

mamba env create --quiet --name stable --file docs/rtd_environment.yaml
mamba activate stable
python -m pip install --upgrade --upgrade-strategy only-if-needed --no-cache-dir .[docs]

export READTHEDOCS_OUTPUT=`pwd`/docs_output
mkdir $READTHEDOCS_OUTPUT
cd docs
python -m sphinx -T -W --keep-going -b html -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html```
Adapting the same commands RTD executes to a local run yields 1.13.4 in the docs, not 1.13.5.dev0. So this rules out the sequence being incorrect. RTD is doing the right things and getting the wrong answer.

 

[stscijgbot-jp]

Comment by Howard Bushouse on JIRA:

Nadia Dencheva Joe Hunkeler when I go to the "stable" link for the JWST RTD it tells me I'm seeing "stable version (1.13.5.dev0+g88dfde9.d20240226)". We never had a 1.13.5 version. B10.1 is 1.13.4 and B10.2 (which was just installed in Ops last week) is 1.14.0. So this page should be build from 1.14.0, since that is now the official stable version of operational code.

[stscijgbot-jp]

Comment by Joe Hunkeler on JIRA:

 

The stable branch has been reset to 1.14.0

$ git checkout --track upstream/stable
$ git reset --hard 1.14.0
$ git --no-pager log -n1 --oneline upstream/stable
f57f0b04c (HEAD -> stable, tag: 1.14.0, upstream/stable, upstream/release/1.14.x, origin/master, origin/HEAD, master) update
metadata for release `1.14.0` (take 3) (#8396)
$ git push upstream -f

Edit:

The RTD build is failing because it pulled in numpy 2.0 (released yesterday, 06/16)

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/conda/stable/lib/python3.11/site-packages/numpy/core/_multiarray_umath.py", line 44, in __getattr__
    raise ImportError(msg)
ImportError: 
A module that was compiled using NumPy 1.x cannot be run in
NumPy 2.0.0 as it may crash. To support both 1.x and 2.x
versions of NumPy, modules must be compiled with NumPy 2.0.
Some module may need to rebuild instead e.g. with 'pybind11>=2.12'.

If you are a user of the module, the easiest solution will be to
downgrade to 'numpy<2' or try to upgrade the affected module.
We expect that some modules will need time to support NumPy 2. 

...

  File "/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/conda/stable/lib/python3.11/site-packages/jwst/resample/resample.py", line 7, in <module>
    from drizzle import cdrizzle
ImportError: numpy.core.multiarray failed to import```

[stscijgbot-jp]

Comment by Howard Bushouse on JIRA:

Joe Hunkeler but why does the banner in the upper-left corner of the page still show the version as 1.13.5dev?

!Screenshot 2024-06-17 at 9.43.19 AM.png!

[braingram]

The stable build failed due to numpy 2.0:
https://readthedocs.org/projects/jwst-pipeline/builds/24718360/
See:
#8565

[braingram]

Oh, what @jhunkeler said :)

[stscijgbot-jp]

Comment by Nadia Dencheva on JIRA:

I believe the 1.13.5.dev.0 tag is set automatically as the next development tag.

Joe Hunkeler Zach Burnett Is there a way to force the RTD build to use the release tag on the "stable" branch?

[jhunkeler]

Normally we git reset --hard the stable branch to point to the latest release tag and push it back up. This triggers a rebuild on the RTD side. If we want to it's also possible to activate automatic builds on our release/x.y.z branches. The benefit being, we don't have to touch anything for the lifetime of a release branch, but we do need to activate builds as new release branches are created.

[jhunkeler]

We can use https://docs.readthedocs.io/en/stable/automation-rules.html to build our tags, or release branches automatically. Enabling this would (I feel like) remove the need for a "stable" branch altogether. If I'm reading this correctly we can configure it to build the latest release tag and set it as the default documentation displayed on the site, instead of whatever comes out of master/main.

[stscijgbot-jp]

Comment by Joe Hunkeler on JIRA:

The following PR was merged yesterday afternoon to address the versioning issue.

#8633

 

The "jwst/stable" branch has been removed. Readthedocs will now automatically generate "stable" documentation using their default semantic versioning rules.

See: https://docs.readthedocs.io/en/stable/versions.html#how-we-envision-versions-working

[stscijgbot-jp]

Comment by Joe Hunkeler on JIRA:

This change will take effect after the next release. Readthedocs builds tags. The previous release did not provide the changes we merged the other day, so that's why the current stable documentation is still showing a "0.1" development tag.

I'm marking this resolved.

[stscijgbot-jp]

Comment by Nadia Dencheva on JIRA:

#8642