Links to sources in docs

Links to sources in docs

[Petr Vorel]

Hi Jonathan, all,

I wonder how links in sources work.

Documentation/userspace-api/check_exec.rst has:

`samples/check-exec/inc.c`_ example.

which leads to link to the source [1]. But if i try to use the same pattern in
Documentation/trace/fprobe.rst:

-See Filter Commands in `Documentation/trace/ftrace.rst`.
+See Filter Commands in Documentation/trace/ftrace.rst.

it does not work:

Documentation/admin-guide/bug-hunting.rst:54: ERROR: Unknown target name: "scripts/decode_stacktrace.sh". [docutils]

Kind regards,
Petr

[1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/samples/check-exec/inc.c

Re: Links to sources in docs

[Jani Nikula]

On Fri, 09 Jan 2026, Petr Vorel <pvorel@suse.cz> wrote:
> Hi Jonathan, all,
>
> I wonder how links in sources work.
>
> Documentation/userspace-api/check_exec.rst has:
>
> `samples/check-exec/inc.c`_ example.

There's this bit at the end of check_exec.rst that defines the link:

.. _samples/check-exec/inc.c:
   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/samples/check-exec/inc.c

The content within the backticks is just the link text, and has no
filename semantics. See [1] for details.


HTH,
Jani.


[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks


>
> which leads to link to the source [1]. But if i try to use the same pattern in
> Documentation/trace/fprobe.rst:
>
> -See Filter Commands in `Documentation/trace/ftrace.rst`.
> +See Filter Commands in Documentation/trace/ftrace.rst.
>
> it does not work:
>
> Documentation/admin-guide/bug-hunting.rst:54: ERROR: Unknown target name: "scripts/decode_stacktrace.sh". [docutils]
>
> Kind regards,
> Petr
>
> [1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/samples/check-exec/inc.c
>

-- 
Jani Nikula, Intel

Re: Links to sources in docs

[Petr Vorel]

> On Fri, 09 Jan 2026, Petr Vorel <pvorel@suse.cz> wrote:
> > Hi Jonathan, all,

> > I wonder how links in sources work.

> > Documentation/userspace-api/check_exec.rst has:

> > `samples/check-exec/inc.c`_ example.

> There's this bit at the end of check_exec.rst that defines the link:

> .. _samples/check-exec/inc.c:
>    https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/samples/check-exec/inc.c

> The content within the backticks is just the link text, and has no
> filename semantics. See [1] for details.

Thanks for a hint, I overlooked it.

We use in LTP sphinx.ext.extlinks [2]:

	'master': (f'{ltp_repo}/blob/master/%s', '%s')

to make file clickable [3]:

	:master:`include/lapi/posix_clocks.h`

then leads to file in git repository. I wonder if this could be useful for
kernel as well.

Kind regards,
Petr

> HTH,
> Jani.


> [1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks
[2] https://github.com/linux-test-project/ltp/blob/master/doc/conf.py
[3] https://linux-test-project.readthedocs.io/en/latest/developers/writing_tests.html#backwards-compatibility
[4] https://github.com/linux-test-project/ltp/blob/master/include/lapi/posix_clocks.h


> > which leads to link to the source [1]. But if i try to use the same pattern in
> > Documentation/trace/fprobe.rst:

> > -See Filter Commands in `Documentation/trace/ftrace.rst`.
> > +See Filter Commands in Documentation/trace/ftrace.rst.

> > it does not work:

> > Documentation/admin-guide/bug-hunting.rst:54: ERROR: Unknown target name: "scripts/decode_stacktrace.sh". [docutils]

> > Kind regards,
> > Petr

> > [1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/samples/check-exec/inc.c

Re: Links to sources in docs

[Petr Vorel]

> > On Fri, 09 Jan 2026, Petr Vorel <pvorel@suse.cz> wrote:
> > > Hi Jonathan, all,

> > > I wonder how links in sources work.

> > > Documentation/userspace-api/check_exec.rst has:

> > > `samples/check-exec/inc.c`_ example.

> > There's this bit at the end of check_exec.rst that defines the link:

> > .. _samples/check-exec/inc.c:
> >    https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/samples/check-exec/inc.c

> > The content within the backticks is just the link text, and has no
> > filename semantics. See [1] for details.

> Thanks for a hint, I overlooked it.

And I also wonder what does clickable links (e.g. [1]) in
Documentation/process/adding-syscalls.rst [2]

    - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness
      check")
    - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc
      conflict")
    - commit bb458c644a59 ("Safer ABI for O_TMPFILE")

I haven't found anything in the document itself, nor in conf.py.

Kind regards,
Petr

[1] https://git.kernel.org/torvalds/c/75069f2b5bfb
[2] https://docs.kernel.org/process/adding-syscalls.html#references-and-sources
...

Re: Links to sources in docs

[Jani Nikula]

On Tue, 13 Jan 2026, Petr Vorel <pvorel@suse.cz> wrote:
>> > On Fri, 09 Jan 2026, Petr Vorel <pvorel@suse.cz> wrote:
>> > > Hi Jonathan, all,
>
>> > > I wonder how links in sources work.
>
>> > > Documentation/userspace-api/check_exec.rst has:
>
>> > > `samples/check-exec/inc.c`_ example.
>
>> > There's this bit at the end of check_exec.rst that defines the link:
>
>> > .. _samples/check-exec/inc.c:
>> >    https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/samples/check-exec/inc.c
>
>> > The content within the backticks is just the link text, and has no
>> > filename semantics. See [1] for details.
>
>> Thanks for a hint, I overlooked it.
>
> And I also wonder what does clickable links (e.g. [1]) in
> Documentation/process/adding-syscalls.rst [2]
>
>     - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness
>       check")
>     - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc
>       conflict")
>     - commit bb458c644a59 ("Safer ABI for O_TMPFILE")
>
> I haven't found anything in the document itself, nor in conf.py.

It's the automarkup extension, configured in conf.py extensions, and
implemented in Documentation/sphinx/automarkup.py.

BR,
Jani.

>
> Kind regards,
> Petr
>
> [1] https://git.kernel.org/torvalds/c/75069f2b5bfb
> [2] https://docs.kernel.org/process/adding-syscalls.html#references-and-sources
> ...

-- 
Jani Nikula, Intel