Update RTD to include multiple versions of Lumino

[afshin]

The Lumino readthedocs.io site should support both Lumino 1 and Lumino 2 docs and needs a re-visit for maintenance.

[gabalafou]

I need to familiarize myself more with Read the Docs, so I'm willing to try to figure out how to

• upgrade current Read the Docs
• add version support

But I don't think I have enough of the big picture of Lumino to make content/copy changes and contributions here.

[afshin]

make content/copy changes and contributions here

Don't worry, the content for now is all contained within doc strings, so if you can generate an RTD page that shows the API documentation for the current version and the previous version, we are good.

[blink1073]

It should be controllable by having an active "Version" for the 1.x branch. See JupyterLab for example:

[blink1073]

@gabalafou, what is your ReadTheDocs username?

[gabalafou]

I didn't have a Read the Docs username before, but it is now the same as my GitHub username: gabalafou.

[blink1073]

Great, you should have an invite now!

[gabalafou]

With #354 merged, I went ahead and made the following changes in the Read The Docs settings:

• Deactivated version stable
• Activated version 1.x
• Set latest to point to main instead of master.
  • Previously it was blank. The RTD UI says, "Leave empty to use the default value for your VCS (eg. trunk or master)." However, the versions page was still showing latest pointing to master until I set it explicitly to main under Admin > Advanced Settings > Default branch.

I discussed the desired final config with @afshin on Tuesday, and the above changes reflect that conversation. He said that he envisioned just two RTD versions: 1.x and latest.

You should now be able to see all of these changes (RTD settings plus code changes from #354) at https://lumino.readthedocs.io.

Therefore, I'm going to close this issue for now.

[gabalafou]

Oh, I almost forgot: a few things before we completely move on from this issue. I created several follow-up issues from this work:

• Use Pydata Sphinx Theme for docs #356. @fcollonval suggested that we do a follow-up to have Lumino use the Pydata Sphinx Theme. I didn't assign this issue to myself because I'm not sure yet whether I will have time for it.

• Fix Typedoc warnings #357. There are a lot of Typedoc warnings that get emitted now when you run yarn docs from the root of the repo.

• Remove GitHub Pages version of docs #358. Should we remove the old GitHub Pages build of the docs? https://jupyterlab.github.io/lumino/.

[fcollonval]

• Deactivated version stable

I would prefer to keep it. It is a good practice to provide a default endpoint that people can bookmark.

[gabalafou]

@afshin can you respond to @fcollonval's comment above?

I was just following your guidance when setting up RTD to just have latest and 1.x but not stable.

Reminder that stable points (I think) to whichever year-month-day-format tag is the latest in Lumino repo, which at the time of this writing is v2022.8.22-alpha.1, I think (although I'm curious whether RTD will pick up a tag with an -alpha suffix as stable).

[fcollonval]

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