[docs] Set up Sphinx doc linting to detect absolute URLs that point to the same project
- Dominant language
- LLVM
- Stars
- 40.5k
- Forks
- 18.7k
- PR merge metrics
- PR metrics pending
Description
Some of our Sphinx docs have absolute URL links that reference documentation in the same project, such as this one: https://github.com/llvm/llvm-project/blob/05c12f14deb9e54b79aea0b210533e7af208386d/clang/docs/LifetimeSafety.md?plain=1#L28
We should have some sort of automated linter that detects same-project documentation references, flags them, and instead encourage people to use :ref: or ":doc:`literal link text `"
@hnrklssn raised this on https://discourse.llvm.org/t/rfc-use-furo-theme-for-clang-docs/91505 , I'm just filing it.
This is probably achievable with a plugin in utils/docs/llvm_sphinx, but maybe there's a better way to lint Sphinx.
Contributor guide
Research direction
Start by reading the Sphinx integration under utils/docs/llvm_sphinx and the example URL in the issue. Determine how same-project absolute documentation URLs can be identified and linted, then verify that the example is flagged while :ref: or :doc: links are accepted.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100