Provide version-specific Tutor docs when running `tutor dev`

michaelwheeler commented 1 year ago

Background

Only docs for the most recent version of Tutor are hosted at docs.tutor.overhang.io, but for a variety of reasons developers using Tutor to improve or extend Open edX may want to use a previous Tutor version during development. In these cases, it would be helpful if a Tutor documentation site for the currently installed Tutor version could be made available at docs.local.overhang.io (or similar) when the development platform is run using tutor dev start.

Tasks

TBD

Notes

Workarounds:

Browse rst files for the appropriate tag on GitHub, where they are displayed in a mostly-formatted way.
Checkout the appropriate versions of tutor source and build docs locally.
Use command line help.

ARMBouhali commented 1 year ago

That's a potential idea for a tutor-contrib-docs plugin ! It would add a tutor command for that with some dev dependencies (which are they?).

Here's an example of how it may work

$ tutor docs 14.1.0
---
Tutor version: 14.1.0
The documentation server is accessible at http://local.overhang.io:7081
Enter Ctrl+C to stop the server

What this command will do:

git checkout <tutor-version> -- docs
generate the docs with make docs
git checkout HEAD -- docs to restore the docs dir to its current version.
Launch the documentation server (no idea which package would be used).

The command help would output these arguments:

usage:
------
    tutor docs [<tutor-version> | nightly | ] [-d]

arguments:
----------
    tutor-version      optional argument to specify which version of tutor's docs you want.
                       Can be any git branch/tag. Defaults to 'latest'
options:
--------
    -d                 daemonize the docs server (run in background)

Notes: If this is ever implemented, I'd rather not add it as a new docker-compose service. Also, if I were @regisb I probably wouldn't include it in the core.

@michaelwheeler @kdmccormick what do you think?

regisb commented 1 year ago

The best solution would be to generate the docs for multiple versions on the original docs website: https://docs.tutor.overhang.io

We would display a javascript widget to switch between different versions, pretty much like the Django docs: https://docs.djangoproject.com/en/4.1/intro/

By default we would display the latest docs. For instance: https://docs.tutor.overhang.io/gettingstarted.html

And when we switched to a different version we would display instead: https://docs.tutor.overhang.io/v14.0.0/gettingstarted.html https://docs.tutor.overhang.io/nightly/gettingstarted.html

My problem is that there is no option to do that out of the box Sphinx. Tutor uses the readthedocs theme and this theme does not have this option either.

Thus, we would have to create our own version-switcher.js script. We could draw inspiration from the pydata theme which has this version-switching capability: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html

So it's quite a bit of work, and I could really use some help.

michaelwheeler commented 1 year ago

@regisb Agree that a Django-like version switcher would be the most desirable solution. I'm trying to become more comfortable with Sphinx for some of my own projects, so I'll certainly take a peak at the pydata implementation to see if I can get a sense of what it would take to bring that feature to the Tutor docs.

As a stopgap, I wonder if Django-style "New/Changed in Tutor 15.1" notices (like those in the Django constraints reference) might provide much of the value with less effort.

@ARMBouhali The proposed plugin you describe sounds useful to me, even if docs were just served with http.server. My big question would be where on the file system would the source and build live? It would be nice if they could be tucked away in TUTOR_ROOT, but I'm not sure if there is an appropriate spot for them there. In any case, I'm happy to explore this option.

regisb commented 1 year ago

I just learned about Zeal and Dash, which are awesome, offline documentation browsers. The tools make it possible to share different versions of the docs in a single RSS feed, which can then be imported. I generated Tutor docs for Zeal (in a format called Docset) and it just works.

I'm wondering if there are users of such tools here? Maybe it would make sense to publish a feed that users could download instead of publishing docs online for older releases?

michaelwheeler commented 1 year ago

Seems appealing. I use a similar web-based tool called DevDocs, and I'd definitely be willing to try out a Tutor docset feed using Dash. If any Tutor plugins get Sphinx docs it would open up the possibility of having them available all in one place too.

Makes me wonder as well how difficult it would be to generate docs in a few different formats (Django provides HTML/ePub/PDF) and add them to GitHub releases as assets.

openedx / wg-devops