Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sphinx Multiversioning #346

Open
wants to merge 287 commits into
base: dev
Choose a base branch
from

Conversation

ZergLev
Copy link
Collaborator

@ZergLev ZergLev commented Apr 5, 2024

Description

Added Sphinx Multiversioning utilising JamesIves/github-deploy-action's feature of saving commit history on gh-pages branch.

You can see a working example here: https://zerglev.github.io/chatsky/master/index.html. Use the version switcher button in the top-right to switch between versions. (It's switched off right now, but it should work in this repo)
Major changes:

  • Can build and deploy documentation for any pre-configured branch or tag. We can build docs for versions up to v0.8.0; versions before that are too different. (due to renaming 'DFF' -> 'Chatsky')
  • Has a version switcher button. (in top right corner) It only shows master (as 'latest'), dev and all tags like v0.9.0 from a specified 'start_version'.
  • Documentation for different versions is saved in separate folders, and you can conveniently switch the folder to view the same file for a different version (if it exists)

Minor details:

  • In case there is no version selected for docs, say, someone used an old link, like https://deeppavlov.github.io/chatsky/index.html, the website will redirect them to master by default.
  • In case someone makes a mistake and types /latest/ within their docs link, it will redirect them to /master/.
  • All relevant links are version-dependent.

Checklist

  • Made a working example with master and dev built separately
  • Version switcher works correctly
  • Using tags to create docs for different versions
  • Pull Requests build docs correctly
  • Deleting old builds before deploying new builds
  • Made all relevant links version-dependent
  • Redirects work now
  • I have performed a self-review of the changes
  • Receive a review and do the required changes

To Consider

  • We could redirect people to chatsky in case someone types dialog_flow_framework, it's very easy to do.
  • Testing Github Pages deployment from main Chatsky repo.
  • Testing documentation building from Chatsky repo.
  • SEO optimization (old links will show the wrong website, even though they will get redirected now) (just need to add a few lines into index.html if we want to do that)
  • Finding a better place/design for the version switcher button. (It's maybe okay now, actually)
  • Update CONTRIBUTING.md (if devel workflow is changed)
  • Update .ignore files, scripts (such as lint), distribution manifest (if files are added/deleted)

Notes:

  • "git stash" and "git checkout" are used during the Github Workflow. I'm not sure if that poses a problem, but everything is returned to it's place in the end, and I don't really know how to do things otherwise. It might just be required. If other workflows just wait for this one, then there can't be a problem, I think. Or if they don't run at the same time.
  • We're always using old conf.py files, meaning the docs will be exactly the same way, they were before - all brand names, pictures, website designs might be outdated.

docs/source/conf.py Outdated Show resolved Hide resolved
@RLKRo RLKRo self-requested a review April 22, 2024 11:20
@RLKRo RLKRo marked this pull request as ready for review April 22, 2024 17:34
Copy link
Member

@RLKRo RLKRo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also approved the run of github actions which returned a couple of errors.
AFAIK pushing new commits here would now retrigger github CI so you can see if the errors are gone.

.github/workflows/build_and_publish_docs.yml Outdated Show resolved Hide resolved
.github/workflows/build_and_publish_docs.yml Outdated Show resolved Hide resolved
docs/source/utils/generate_tutorials.py Outdated Show resolved Hide resolved
docs/source/utils/generate_tutorials.py Outdated Show resolved Hide resolved
docs/source/utils/generate_tutorials.py Outdated Show resolved Hide resolved
docs/source/conf.py Outdated Show resolved Hide resolved
docs/source/conf.py Outdated Show resolved Hide resolved
docs/source/poly.py Outdated Show resolved Hide resolved
docs/source/poly.py Outdated Show resolved Hide resolved
docs/source/setup.py Outdated Show resolved Hide resolved
@ZergLev ZergLev requested a review from RLKRo May 2, 2024 15:18
@RLKRo
Copy link
Member

RLKRo commented Sep 11, 2024

  • Redirect chatsky/path to chatsky/master/path (maybe also rename to latest).
  • Do not use patched polyversion -- pypi doesn't accept that. Can patch sys.argv in scripts/docs.py.
  • Version switcher displays "dev" when on dev but "Choose version" when on master.

@RLKRo
Copy link
Member

RLKRo commented Sep 16, 2024

Fix tutorial links:
image
Colab link does not contain version;
github link always links to master.

ZergLev and others added 30 commits November 27, 2024 20:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants