astral-sh / astral-sh/ruff

Rule Documentation UX improvement suggestions: navigation + link to source

Open
#13,367 4 comments 0 reactions 0 assignees View on GitHub
documentation wish
Dominant language
Rust
Stars
49.7k
Forks
2.4k
Avg merge
2d 1h
Merged PRs (30d)
458

Description

Hi there,

As user I frequently wish the docs would have these functionalities:

## Navigation between rule pages

Navigate to another rule of the same prefix, e.g. on any rule page https://docs.astral.sh/ruff/rules/suppressible-exception/ it would be great to be able to navigate to the previous/next rule with the same prefix. This would be a nicer experience to explore a set of rules then going back and opening each rule in a new tab from the (huge) all rules page.

One option would be to enable footer navigation: https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#navigation

Moreover/alternatively, I could imagine:

1. being able to navigate back from the rule page, e.g. making "Derived from the XXX linter." clickable link.
2. a navbox with the rules on the bottom of each rule page (like wikipedia has, personal favourite option):

Markdown example:

| pyupgrade (UP) |
|------------------------------------------------------------------------------------------------------------|
| [useless-metaclass-type](#) (UP001) · [type-of-primitive](#) (UP003) · [useless-object-inheritance](#) (UP004) · [deprecated-unittest-alias](#) (UP005) · [non-pep585-annotation](#) (UP006) · [non-pep604-annotation](#) (UP007) · [super-call-with-parameters](#) (UP008) · [utf8-encoding-declaration](#) (UP009) · [unnecessary-future-import](#) (UP010) · [lru-cache-without-parameters](#) (UP011) · [unnecessary-encode-utf8](#) (UP012) · [convert-typed-dict-functional-to-class](#) (UP013) · [convert-named-tuple-functional-to-class](#) (UP014) · [redundant-open-modes](#) (UP015) · [datetime-timezone-utc](#) (UP017) · [native-literals](#) (UP018) · [typing-text-str-alias](#) (UP019) · [open-alias](#) (UP020) · [replace-universal-newlines](#) (UP021) · **[replace-stdout-stderr](#) (UP022)** · [deprecated-c-element-tree](#) (UP023) · [os-error-alias](#) (UP024) · [unicode-kind-prefix](#) (UP025) · [deprecated-mock-import](#) (UP026) · [unpacked-list-comprehension](#) (UP027) · [yield-in-for-loop](#) (UP028) · [unnecessary-builtin-import](#) (UP029) · [format-literals](#) (UP030) · [printf-string-formatting](#) (UP031) · [f-string](#) (UP032) · [lru-cache-with-maxsize-none](#) (UP033) · [extraneous-parentheses](#) (UP034) · [deprecated-import](#) (UP035) · [outdated-version-block](#) (UP036) · [quoted-annotation](#) (UP037) · [non-pep604-isinstance](#) (UP038) · [unnecessary-class-parentheses](#) (UP039) · [non-pep695-type-alias](#) (UP040) · [timeout-error-alias](#) (UP041) · [replace-str-enum](#) (UP042) · [unnecessary-default-type-args](#) (UP043) |

## Link to source/fixtures

Rule documentation as is does not answer questions such as:
- Rule X violation detected, but I suspect it's a false positive, what exact cases does this rule match?
- I would expect Rule Y to trigger, but it did not, is that on purpose?

To allow the user to more easily answer these questions before opening an issue, it would be helpful to link the source code and/or the Python fixtures for a rule on that page. Going from the root directory on GitHub, this can save around 7 clicks, e.g. https://github.com/astral-sh/ruff/blob/main/crates/ruff_linter/resources/test/fixtures/flake8_tidy_imports/TID251.py.

Possible implementation: https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#code-actions

## Code block titles

Minor tweak to make instantly clear which snippet to take (alternatives as "bad" | "bad.py" and "good" | "good.py" could work too):

As done in uv, e.g. https://github.com/astral-sh/uv/blob/main/docs/guides/scripts.md

https://squidfunk.github.io/mkdocs-material/reference/code-blocks/

Happy to contribute a PR, but first opening it up for discussion

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the documentation setup against the referenced MkDocs Material pages for footer navigation, repository links, and code blocks. The issue mentions the fixture path crates/ruff_linter/resources/test/fixtures/flake8_tidy_imports/TID251.py but no local documentation file; clarify the selected scope and consider the work done when the agreed navigation, source or fixture links, and code-block titles are present.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown, python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.