MESAHub/mesa

Docs request: show warning banner if viewing docs from earlier MESA versions

Closed this issue · 4 comments

mjoyceGR commented

Greetings from the 2024 MESA Summer School

It was pointed out to @JMombarg and me that Googling something related to MESA documentation can and will pull up the docs for a random MESA version (in this example, 22.05.1).

We are now trying to revise the docs such that a warning banner like the one that appears in index.rst

.. warning::

   These docs are always under active development. Some sections are more complete than others.

appears if one is viewing the docs associated to a MESA version that is not the most recent stable release.

We've gotten as far as putting modifications in conf.py that allow this

# -- Set Current Version here ------------------------------------------------
current_version = 'r24.03.1'

# -- Project information -----------------------------------------------------

project = 'MESA'
copyright = '2024, The MESA Team'
author = 'The MESA Team'
release = 'This is the release string' 
version = 'r22.05.1' #'main'

# Check if the current version matches the version of this documentation
is_old_version = version != current_version

(etc)

but we can't see a way around manually modifying conf.py in all previous versions of the MESA documentation. I guess it's fine to do that, but it would mean changing stable releases (in a trivial way, but still).

Does anyone have any better ideas?

pmocz commented

The MESA documentation is hosted on readthedocs, is that right? There may be a way to automatically enable it: https://docs.readthedocs.io/en/stable/versions.html#version-warning

mjoyceGR commented

@JMombarg found that too but we couldn't find an option in the admin settings to activate this... maybe @rhdtownsend knows?

rhdtownsend commented
pmocz commented

This was fixed after switching git tags to follow PEP 440 standards, and building docs from tags (so readthedocs can automatically add banners and detect stable). It may be beneficial for us in the future to consider going back to building docs from branches, in which case we will also need to change the branch names to follow PEP 440 standards

  • 👍1
  • 🎉1