llvm / llvm/llvm-project

[docs] Set up Sphinx doc linting to detect absolute URLs that point to the same project

Open
#214,861 1 comment 1 reaction 0 assignees View on GitHub
documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.