Message-ID: <437912a24e94673c2355a2b7b50c3c4b6f68fcc6@intel.com>
Date: Fri, 29 Aug 2025 15:18:20 +0300
From: Jani Nikula <jani.nikula@...el.com>
To: Bagas Sanjaya <bagasdotme@...il.com>, Linux Kernel Mailing List
 <linux-kernel@...r.kernel.org>, Linux Documentation
 <linux-doc@...r.kernel.org>, Linux DAMON <damon@...ts.linux.dev>, Linux
 Memory Management List <linux-mm@...ck.org>, Linux Power Management
 <linux-pm@...r.kernel.org>, Linux Block Devices
 <linux-block@...r.kernel.org>, Linux BPF <bpf@...r.kernel.org>, Linux
 Kernel Workflows <workflows@...r.kernel.org>, Linux KASAN
 <kasan-dev@...glegroups.com>, Linux Devicetree
 <devicetree@...r.kernel.org>, Linux fsverity <fsverity@...ts.linux.dev>,
 Linux MTD <linux-mtd@...ts.infradead.org>, Linux DRI Development
 <dri-devel@...ts.freedesktop.org>, Linux Kernel Build System
 <linux-lbuild@...r.kernel.org>, Linux Networking <netdev@...r.kernel.org>,
 Linux Sound <linux-sound@...r.kernel.org>
Cc: Thomas Gleixner <tglx@...utronix.de>, Borislav Petkov <bp@...en8.de>,
 Peter Zijlstra <peterz@...radead.org>, Josh Poimboeuf
 <jpoimboe@...nel.org>, Pawan Gupta <pawan.kumar.gupta@...ux.intel.com>,
 Jonathan Corbet <corbet@....net>, SeongJae Park <sj@...nel.org>, Andrew
 Morton <akpm@...ux-foundation.org>, David Hildenbrand <david@...hat.com>,
 Lorenzo Stoakes <lorenzo.stoakes@...cle.com>, "Liam R. Howlett"
 <Liam.Howlett@...cle.com>, Vlastimil Babka <vbabka@...e.cz>, Mike Rapoport
 <rppt@...nel.org>, Suren Baghdasaryan <surenb@...gle.com>, Michal Hocko
 <mhocko@...e.com>, Huang Rui <ray.huang@....com>, "Gautham R. Shenoy"
 <gautham.shenoy@....com>, Mario Limonciello <mario.limonciello@....com>,
 Perry Yuan <perry.yuan@....com>, Jens Axboe <axboe@...nel.dk>, Alexei
 Starovoitov <ast@...nel.org>, Daniel Borkmann <daniel@...earbox.net>,
 Andrii Nakryiko <andrii@...nel.org>, Martin KaFai Lau
 <martin.lau@...ux.dev>, Eduard Zingerman <eddyz87@...il.com>, Song Liu
 <song@...nel.org>, Yonghong Song <yonghong.song@...ux.dev>, John Fastabend
 <john.fastabend@...il.com>, KP Singh <kpsingh@...nel.org>, Stanislav
 Fomichev <sdf@...ichev.me>, Hao Luo <haoluo@...gle.com>, Jiri Olsa
 <jolsa@...nel.org>, Dwaipayan Ray <dwaipayanray1@...il.com>, Lukas Bulwahn
 <lukas.bulwahn@...il.com>, Joe Perches <joe@...ches.com>, Andrey Ryabinin
 <ryabinin.a.a@...il.com>, Alexander Potapenko <glider@...gle.com>, Andrey
 Konovalov <andreyknvl@...il.com>, Dmitry Vyukov <dvyukov@...gle.com>,
 Vincenzo Frascino <vincenzo.frascino@....com>, Rob Herring
 <robh@...nel.org>, Krzysztof Kozlowski <krzk+dt@...nel.org>, Conor Dooley
 <conor+dt@...nel.org>, Eric Biggers <ebiggers@...nel.org>, tytso@....edu,
 Richard Weinberger <richard@....at>, Zhihao Cheng
 <chengzhihao1@...wei.com>, David Airlie <airlied@...il.com>, Simona Vetter
 <simona@...ll.ch>, Maarten Lankhorst <maarten.lankhorst@...ux.intel.com>,
 Maxime Ripard <mripard@...nel.org>, Thomas Zimmermann
 <tzimmermann@...e.de>, Nathan Chancellor <nathan@...nel.org>, Nicolas
 Schier <nicolas.schier@...ux.dev>, Ingo Molnar <mingo@...hat.com>, Will
 Deacon <will@...nel.org>, Boqun Feng <boqun.feng@...il.com>, Waiman Long
 <longman@...hat.com>, "David S. Miller" <davem@...emloft.net>, Eric
 Dumazet <edumazet@...gle.com>, Jakub Kicinski <kuba@...nel.org>, Paolo
 Abeni <pabeni@...hat.com>, Simon Horman <horms@...nel.org>, Shay Agroskin
 <shayagr@...zon.com>, Arthur Kiyanovski <akiyano@...zon.com>, David
 Arinzon <darinzon@...zon.com>, Saeed Bishara <saeedb@...zon.com>, Andrew
 Lunn <andrew@...n.ch>, Liam Girdwood <lgirdwood@...il.com>, Mark Brown
 <broonie@...nel.org>, Jaroslav Kysela <perex@...ex.cz>, Takashi Iwai
 <tiwai@...e.com>, Alexandru Ciobotaru <alcioa@...zon.com>, The AWS Nitro
 Enclaves Team <aws-nitro-enclaves-devel@...zon.com>, Jesper Dangaard
 Brouer <hawk@...nel.org>, Bagas Sanjaya <bagasdotme@...il.com>, Laurent
 Pinchart <laurent.pinchart@...asonboard.com>, Steve French
 <stfrench@...rosoft.com>, Meetakshi Setiya <msetiya@...rosoft.com>, Greg
 Kroah-Hartman <gregkh@...uxfoundation.org>, "Martin K. Petersen"
 <martin.petersen@...cle.com>, Bart Van Assche <bvanassche@....org>, Thomas
 Weißschuh <linux@...ssschuh.net>, Masahiro Yamada
 <masahiroy@...nel.org>
Subject: Re: [PATCH 00/14] Internalize www.kernel.org/doc cross-reference

On Fri, 29 Aug 2025, Bagas Sanjaya <bagasdotme@...il.com> wrote:
> Cross-references to other docs (so-called internal links) are typically
> done following Documentation/doc-guide/sphinx.rst: either simply
> write the target docs (preferred) or use :doc: or :ref: reST directives
> (for use-cases like having anchor text or cross-referencing sections).
> In some places, however, links to https://www.kernel.org/doc
> are used instead (outgoing, external links), owing inconsistency as
> these requires Internet connection only to see docs that otherwise
> can be accessed locally (after building with ``make htmldocs``).
>
> Convert such external links to internal links. Note that this does not
> cover docs.kernel.org links nor touching Documentation/tools (as
> docs containing external links are in manpages).

FWIW, I'd much prefer using :ref: on rst anchors (that automatically
pick the link text from the target heading) instead of manually adding
link texts and file references.

i.e.

.. _some_target:

Heading After Some Target
=========================

See :ref:`some_target`.

Will generate "See Heading After Some Target".


BR,
Jani.


-- 
Jani Nikula, Intel

Powered by blists - more mailing lists