More intuitive branch names for documentation versions on Read the Docs ?

[unman]

Issue #10251 relates to branch names for documentation versions on Read the Docs

I'd like to bring this to a close with agreement.

The default names on RTD are "latest" to track main branch, and
"stable" to track the highest versioned branch.

There are arguments in favour of changing this. For what it's worth,
most RTD projects seem to use the default; Fedora uses "latest" for
the most recent release; Debian uses "stable" for the most recent
release, (and "oldstable" for the one before.)

These projects do not seem to see any issue with using these names in
their documentation, instead of URLS that point to specific releases,
(although they may support that also).

I do not know if it's possible to change the default namings in RTD to
keep the automatic updating. The documentation isnt particularly clear
on this, and (ironically) the documentation on building a working local
RTD on Debian is woeful.

It IS possible to change the default view to show documentation for the
stable branch. We should do this, under whatever name is chosen.

I think we need to establish:
1. Is it possible to change the default names - latest and stable?
2. If so, what names should we use?
3. If we do, is it possible to retain automatic generation of docs for
the most recent versioned branch?
4. If we do change from defaults, and it is not possible to retain
automatic generation, can we manually set our choice to point to the
most recent versioned branch?

2 is for general discussion.
1,3,4 need input from folk familiar with RTD.

unman

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On Fri, Oct 10, 2025 at 01:16:16PM +0100, 'unman' via qubes-devel wrote:
> Issue #10251 relates to branch names for documentation versions on Read the Docs
>
> I'd like to bring this to a close with agreement.
>
> The default names on RTD are "latest" to track main branch, and
> "stable" to track the highest versioned branch.
>
> There are arguments in favour of changing this. For what it's worth,
> most RTD projects seem to use the default; Fedora uses "latest" for
> the most recent release; Debian uses "stable" for the most recent
> release, (and "oldstable" for the one before.)
>
> These projects do not seem to see any issue with using these names in
> their documentation, instead of URLS that point to specific releases,
> (although they may support that also).
>
> I do not know if it's possible to change the default namings in RTD to
> keep the automatic updating. The documentation isnt particularly clear
> on this, and (ironically) the documentation on building a working local
> RTD on Debian is woeful.
>
> It IS possible to change the default view to show documentation for the
> stable branch. We should do this, under whatever name is chosen.
>
> I think we need to establish:
> 1. Is it possible to change the default names - latest and stable?

In practice we can choose any names. The automatically updated "stable"
name is I think hardcoded, but IMO we don't need to use this mechanism -
it's not much work to switch branch every 2 years or so when new qubes
version gets released.

> 2. If so, what names should we use?

This is a very good question. To recap the issue, we have the following
proposals:
1. "latest" for development version, "stable" for most recent stable
version, "4.2" etc for older versions
2. "testing" for development version, "latest" for most recent stable
version, "4.2" etc for older versions
3. always use specific version like "4.2", "4.3"
4. some mix of the above

Unfortunately, version aliases seems to be not implemented yet
(https://github.com/readthedocs/readthedocs.org/issues/5318), so one
branch can have only a single version (it's impossible to have 4.2
visible as both "4.2" and "stable" at the same time).

Personally, I like 1 or 2. And include which version that actually is in
the documentation title (or somewhere else that is always visible).

> 3. If we do, is it possible to retain automatic generation of docs for
> the most recent versioned branch?

It's possible to add automation rules to set default version:
https://docs.readthedocs.io/page/guides/automation-rules.html

But as said above, we don't do new Qubes OS releases that often, it's
IMO okay to simply switch default manually as part of release checklist.

> 4. If we do change from defaults, and it is not possible to retain
> automatic generation, can we manually set our choice to point to the
> most recent versioned branch?

We can set any mapping branch -> version.

> 2 is for general discussion.
> 1,3,4 need input from folk familiar with RTD.
>
> unman

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAmjpAHAACgkQ24/THMrX
1ywHFwf+MTKpFZfK4h+cUfHsBPIBwI7aFBzg6H3J2kAAHtJRX9cJcqvWcYVScOtc
qMLH08tYFTq5peyRFz3WYaan3raGHAbBX2C0EGc47vzuSFuh/ukMgATMHxwBVMqg
1iM8dzRG2MXqU8o9kb228+8/mDWnUuCTCJWPeIZcIzTQGoiWcXDxO8hOD0oH0DDX
eKvsu7OI0dVAHF+n0bou9bFNdCa+26pn2xVFgltow0j20E91M8WoxU2nu4baOE/P
7hbAAPdS7R6sM7TSvlE97yPjbHBtsSieVfz8GrvDcWaXGVB/5PGm5ACTYgV6kDlI
bvQGic8JZ6SKye6k5Jlo5r43shO05w==
=8wX1
-----END PGP SIGNATURE-----

[unman]

I agree that a manual change would not be great effort, if the automatic
system can be turned off.

.
>
> > 2. If so, what names should we use?
>
> This is a very good question. To recap the issue, we have the following
> proposals:
> 1. "latest" for development version, "stable" for most recent stable
> version, "4.2" etc for older versions
> 2. "testing" for development version, "latest" for most recent stable
> version, "4.2" etc for older versions
> 3. always use specific version like "4.2", "4.3"
> 4. some mix of the above
>
> Unfortunately, version aliases seems to be not implemented yet
> (https://github.com/readthedocs/readthedocs.org/issues/5318), so one
> branch can have only a single version (it's impossible to have 4.2
> visible as both "4.2" and "stable" at the same time).
>
> Personally, I like 1 or 2. And include which version that actually is in
> the documentation title (or somewhere else that is always visible).

There is also:
5. "testing" and "stable"
(if that is not subsumed under your 4.
This is the one I favor.

>
> > 3. If we do, is it possible to retain automatic generation of docs for
> > the most recent versioned branch?
>
> It's possible to add automation rules to set default version:
> https://docs.readthedocs.io/page/guides/automation-rules.html
>
> But as said above, we don't do new Qubes OS releases that often, it's
> IMO okay to simply switch default manually as part of release checklist.

Agreed.

>
> > 4. If we do change from defaults, and it is not possible to retain
> > automatic generation, can we manually set our choice to point to the
> > most recent versioned branch?
>
> We can set any mapping branch -> version.

OK

Thanks for input.