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

Merged
merged 288 commits into from
Feb 18, 2025
Merged

Sphinx Multiversioning #346

merged 288 commits into from
Feb 18, 2025

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.

@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.

@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 27 commits November 27, 2024 20:50
@RLKRo RLKRo merged commit ff092c5 into deeppavlov:dev Feb 18, 2025
11 of 17 checks passed
@RLKRo RLKRo mentioned this pull request Feb 18, 2025
RLKRo added a commit that referenced this pull request Feb 18, 2025
# Changelog

## Breaking Changes

- Dropped support for python 3.8; added support for python 3.12 (#400);
- Reworked DB architecture to support partials turn reads/writes (#93).
  Old Context storages are incompatible with the new ones.
  See tutorial Context Storages: 8 for more info;
- `Context.labels`, `Context.requests`, `Context.responses` are now only
lazily loaded (#93).
  Items from older turns can be loaded on demand.
  Their `__getitem__` and `get` methods are now async.


## Features 

- Added `LLMResponse` and `LLMCondition` classes that allow using LLMs
(#376).
See the new LLM Integration tutorials and LLM user guide for more info;
- Added option to extract group slots partially (#394).
  See tutorial Slots: 2 for more information;
- `Message.original_message` is replaced with `Message.origin` which
stores both
the original message and the interface from which the message originated
(#398);
- Added `Context.current_turn_id` field which stores the number of the
current turn (#93);
- Added `Context.created_at`, `Context.updated_at` timestamp fields
(#93);
- Added `Context.turns` property which allows iterating over
requests/labels/responses by their turn ids (#93);
- `Context.labels`, `Context.requests`, `Context.responses` now support
slicing (#93).
`__getitem__`, `__setitem__` and `__delitem__` methods can now accept
slices of turn ids in addition to single turn id.
`get` method can now accepts iterable of turn ids in addition to single
turn id.


## Documentation

- Documentation is now versioned (#346, #409).
You can select preferred version via the drop-down menu in the top-right
corner.


## Developer changes

- Context now has field `origin_interface` to store name of the
interface that created it (#398);
- Added script `docs_no_docker` for building documentation without
docker (ef11ff9);
- Added in-RAM context storage to be the default one instead of a plain
dict (#93);
- Removed methods `Context.add_request`, `Context.add_label` and
`Context.add_response` (#93).
  Use setters with `Context.current_turn_id` instead.
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