search

desy-ml / cheetah

Fast and differentiable particle accelerator optics simulation for reinforcement learning and optimisation applications.
https://cheetah-accelerator.readthedocs.io
GNU General Public License v3.0
25 stars 12 forks source link

Add notification in ReadtheDocs if displaying the latest version #175

Open cr-xu opened 2 weeks ago

cr-xu commented 2 weeks ago

Users should receive notification if they are viewing the doc page of an older version or the latest (probably unstable) version from main branch.

This would prevent people from getting confused like #174.

@jank324 I think this can be configured by admin in RTD (c.f. https://docs.readthedocs.io/en/stable/versions.html#version-warning)?

jank324 commented 2 weeks ago

I've activated the notification.

I've also built a special v0.6.3 docs, but that's currently identical to stable.

I also realised, we can change which docs are shown by default. This is currently set to latest, which builds directly from the master branch. We could think about if it should point to stable instead, which builds from the last release.

However, the confusion in #174 didn't actually result from the docs. Funnily enough, @Hespe ran into exactly the same issue just the day before 😄. In both cases, they saw the code example that you see first when finding Cheetah on GitHub ... which is on the current master branch, but they had the most recent release installed. While notifying people in the docs is a good idea, this wouldn't have prevented either confusion. This is also a unique situation right now, where the code example isn't compatible with both the latest release and the master branch. We haven't really been in this situation before and we are unlikely to be in it again. So maybe the solution here is just to release v0.7 soon (#165).