Rule Documentation UX improvement suggestions: navigation + link to source

[sbrugman]

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

[sbrugman]

Example of what the navbox approach could look like:

Table

Collapsable Navbox

[MichaReiser]

I do find the navbox very verbose and hard to parse. It also lacks any relevant description or additional information where it is unclear to me what the advantage is over just having the information in the rules table.

[sbrugman]

I do agree. What about the alternative of enabling "next" and "previous" navigation for rules? (like the uv docs has. pylint does it too)

[MichaReiser]

I do agree. What about the alternative of enabling "next" and "previous" navigation for rules? (like the uv docs has. pylint does it too)

I'm open to that, although it's unclear to me if there's a natural order for reading the rules (from start to end). How would next and previous work? Would it only navigate between rules of the same category, or is it cross-categories (the next button of a category last rule goes to the next category's first rule)?