Rule Documentation UX improvement suggestions: navigation + link to source
- 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
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