Versioned documentation
- Dominant language
- Rust
- Stars
- 49.6k
- Forks
- 2.4k
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 435
Description
As always - thanks for the amazing tool ❤️
I have seen mention of Ruff lacking versioned documentation (e.g. [here](https://github.com/astral-sh/ruff/pull/9018#issuecomment-1844096218) @MichaReiser), but cannot find if it is on the to-do list?
Reasoning for this question/feature-request: it can be time-consuming when working on projects that each use a different version, plus vscode devcontainers with the ruff extension that may ship with a different version. It is not always possible to simply update all versions, unfortunately. The end result is fixing TOML parsing errors by trial-and-error, because the deployed docs aren't relevant for older versions.
------------------------
I don't know if it has already been investigated(?), but it looks like there is a versioning capability that can be integrated into the existing mkdocs setup via [mike](https://github.com/jimporter/mike). Perhaps the following config could be added to the `mkdocs.generated.yml` file in the [generation script](https://github.com/astral-sh/ruff/blob/ef2798f758e03fa659d1ba2973ddd59515400978/scripts/generate_mkdocs.py)?
```yaml
extra:
version:
provider: mike
```
There are then more options to only publish certain versions (releases) and set a default landing page version, a warning banner if the viewer is looking at an old version -- the regular stuff.
_How hard can it be?™_ 😅
Contributor guide
Research direction
Start with scripts/generate_mkdocs.py and the generated mkdocs.generated.yml configuration, then review how the existing MkDocs publishing setup handles releases. Evaluate the proposed mike integration and define which released versions should be published, which version is the default, and how older-version warnings should appear. Done means the documentation can be selected by Ruff version and remains accurate for older releases.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- yaml
- Domain
- documentation, release
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100