1533430 - Support multiple versions of generated docs

Status: NEW

(Developer Infrastructure :: Source Documentation, enhancement, P3)

Description

[Andrew Halberstadt [:ahal]]

It would be great to host multiple versions of our documentation on firefox-source-docs, e.g central, beta, release.

While uploading these to the server under a branch specific directory will be easy enough, it would also be nice to have a little dropdown that lets you switch between versions like readthedocs gives you.

I found this potential way of implementing it:
https://robpol86.github.io/sphinxcontrib-versioning/master/index.html

Comment 1

[Andrew Halberstadt [:ahal]]

The above link looks defunct, but here's a fork:
https://sphinx-versions.readthedocs.io/en/latest/index.html

Comment 2

[Andrew Halberstadt [:ahal]]

That module sort of seems like it's tied to git branches. Might still be possible to use it somehow, but not sure.

I also discovered that we already do have old copies of the docs from other branches lying around, you just have to manually specify the version number:
https://firefox-source-docs.mozilla.org/main/69.0/

So this bug is more about making that discoverable than anything else. E.g, preferably by adding some sort of drop-down version switcher.

Comment 3

[Sylvestre Ledru [:Sylvestre]]

hmm, I was going to report comment #2 as a bug

We don't want to keep old versions as they are referenced.
For example, I was looking for the mozlint doc and was provided the doc from version 65:
https://firefox-source-docs.mozilla.org/main/65.0/python/mozlint.html

Which isn't what I want.
I think we should only keep doc of maintained versions of Firefox.

Ahal, do you know own that stuff? thanks

Comment 4

[Andrew Halberstadt [:ahal]]

What's the problem you'd like solved exactly? What do you mean "was provided"?

To get the latest version you can visit one of:
https://firefox-source-docs.mozilla.org/python/mozlint.html
https://firefox-source-docs.mozilla.org/main/latest/python/mozlint.html

The docs for older versions could be useful for people who are working off of beta/release. They do automatically expire after awhile, version 63 no longer exists.

It might be good to rename these to "release", "beta", etc instead of the version number.. but then we'd need to get the DocUp task running on those branches and change the upload logic.

Comment 5

[Sylvestre Ledru [:Sylvestre]]

Sorry, let me rephrase :)
I don't think it is providing any value or helping anyone to have the doc of 65 available. This isn't release or ESR.
We should provide documentation for maintained version (and renaming them would be great too)

Comment 6

[Andrew Halberstadt [:ahal]]

Yeah makes sense.

Just a bit of context.. Right now the docs aren't built off of the old branches. What happens is we only upload from mozilla-central, but we do it to three places every time:
<root>
<root>/main/latest
<root>/main/<version>

The first two locations get overwritten, but the last just hangs around until the expiry time. So once the cut-off happens, it's no longer possible to change those older versions (even if pushing a doc change to beta). The expiry was likely originally set to roughly match our release schedule, but our schedule is now shorter so the expiry should be updated. I'm not 100% sure how to do that, maybe we can add it to the WebsiteConfiguration API call.

But changing the name will involve actually running these tasks on the associated branches.

Comment 7

[Sylvestre Ledru [:Sylvestre]]

I wonder if we should not wontfix this one.
too much work and not a real need.
Andrew, agreed?

Comment 8

[Andrew Halberstadt [:ahal]]

I don't think it would be that much work (maybe a day or two), and I can definitely imagine use cases for it (e.g, referencing API docs for the latest mozilla-release). That said I do agree we are unlikely to prioritize this anytime soon.

I'd be inclined to leave the bug open for the future, but if you want to close it for some reason I guess that's fine.