Docs for previous versions?

[thvasilo]

Summary

I would like to have easy access to the documentation of previous versions of the package.

Motivation

Different users of the project will run different versions of the package. We would like to be able refer to documentation that is relevant to the version we're using.

AFAI can tell, LightGBM ReadTheDocs provides only the latest version and a tag named docs-jlamb.

References

Read the Docs supports documentation versioning, so this would be really useful for users of older versions of the package.

For example, for XGBoost, if I wanted to check the docs for version say 1.2.0 I'd go to this.

[jameslamb]

Thanks for using LightGBM and for taking the time to write this up!

You're right, today LightGBM's documentation is built from the current state of its master branch. I agree with your suggestion that it would be useful for people to be able to read a version of the documentation rendered from a specific release!

---

@StrikerRUS have you looked into this before? Reading https://docs.readthedocs.io/en/stable/versions.html, I wonder if we are not getting it automatically because LightGBM release tags start with a v.

You should push a tag for each version of your project. These tags should be numbered in a way that is consistent with semantic versioning. This will map to your stable branch by default.

We in fact are parsing your tag names against the rules given by PEP 440. This spec allows “normal” version numbers like 1.4.2 as well as pre-releases. An alpha version or a release candidate are examples of pre-releases and they look like this: 2.0a1.

We only consider non pre-releases for the stable version of your documentation.

It looks like xgboost keeps a long-lived branch for every release.

That same readthedocs page says those long-lived branches are supported as well.

If you have documentation changes on a long-lived branch, you can build those too. This will allow you to see how the new docs will be built in this branch of the code. Generally you won’t have more than 1 active branch over a long period of time. The main exception here would be release branches, which are branches that are maintained over time for a specific release number.

[StrikerRUS]

We can activate docs for any existing branch/tag in our repo easily:

However, I don't know how make automatic builds for new releases. Probably this is impossible. But we can include this point in our release check-list.

[StrikerRUS]

I guess it's too late for previous releases due to issues and conflicts in tools we use for docs build process, e.g. refer to 5771a97 or 30607d8, but as I said before we can start with current release.

[jameslamb]

Oh great, ok! 🎉

However, I don't know how make automatic builds for new releases

Yes it's interesting, the documentation at https://docs.readthedocs.io/en/stable/versions.html is sort of written like a proposal, not documentation of how RTD actually works haha. Some parts of it make it seems like we should get versioned docs automatically but clearly that hasn't been happening.

I think it would be great to start doing this as a part of releases going forward.

@thvasilo if you want to try building the docs for an older versions yourself, you can try checking out an older release tag and following the instructions at https://github.com/microsoft/LightGBM/tree/master/docs#build. But as @StrikerRUS noted, you might run into issues with dependency versions. If you try to build an old version of the docs, you might want to use the latest version of the docs dependencies at https://github.com/microsoft/LightGBM/blob/master/docs/requirements.txt.

[thvasilo]

I'll give that a shot thanks!

…

On Wed, Apr 28, 2021 at 9:07 AM James Lamb ***@***.***> wrote: Oh great, ok! 🎉 However, I don't know how make automatic builds for new releases Yes it's interesting, the documentation at https://docs.readthedocs.io/en/stable/versions.html is sort of written like a proposal, not documentation of how RTD actually works haha. Some parts of it make it seems like we should get versioned docs automatically but clearly that hasn't been happening. I think it would be great to start doing this as a part of releases going forward. @thvasilo <https://github.com/thvasilo> if you want to try building the docs for an older versions yourself, you can try checking out an older release tag and following the instructions at https://github.com/microsoft/LightGBM/tree/master/docs#build. But as @StrikerRUS <https://github.com/StrikerRUS> noted, you might run into issues with dependency versions. If you try to build an old version of the docs, you might want to use the latest version of the docs dependencies at https://github.com/microsoft/LightGBM/blob/master/docs/requirements.txt. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4236 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACFBHI7BUKWA3WQTBY23ZVLTLAXD3ANCNFSM43VXE4WA> .

[StrikerRUS]

@jameslamb OK, let me start from the most recent release!
Just triggered a build for v3.2.1 tag.

[StrikerRUS]

Done!

Unfortunately, R-API link (and back link from it) is hardcoded to the latest version:
#2415

[StrikerRUS]

Added point to release check-list.
#4169 (comment)

[jameslamb]

Ah ok great, thank you very much! Maybe we can figure out the R link in the future, but I don't think it's urgent.