Open Bug 1533430 Opened 2 years ago Updated 2 years ago

Support multiple versions of generated docs

Categories

(Firefox Build System :: Documentation Infrastructure, enhancement)

enhancement
Not set
normal

Tracking

(Not tracked)

People

(Reporter: ahal, Unassigned)

References

(Blocks 1 open bug)

Details

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

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.

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

Flags: needinfo?(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.

Flags: needinfo?(ahal)

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)

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.

You need to log in before you can comment on or make changes to this bug.