Links to sources in docs
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
Quoted 7 lines · Petr Vorel
Hi Jonathan, all,
I wonder how links in sources work.
Documentation/userspace-api/check_exec.rsthas:
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
Quoted 16 lines
which leads to link to the source [1]. But if i try to use the same pattern in
Documentation/trace/fprobe.rst:(quoted diff) +1
-1-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
Signature · 1 line
Jani Nikula, Intel
Quoted 9 lines · Petr Vorel
Quoted 7 lines
Hi Jonathan, all,
I wonder how links in sources work.
Documentation/userspace-api/check_exec.rsthas:
samples/check-exec/inc.c_ example.
Quoted 7 lines
There's this bit at the end of
check_exec.rstthat 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.cThe 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
Quoted 5 lines
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
Quoted 14 lines
Quoted 14 lines
which leads to link to the source [1]. But if i try to use the same pattern in
Documentation/trace/fprobe.rst:(quoted diff) +1
-1-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
Quoted 11 lines
Quoted 10 lines · Petr Vorel
Quoted 7 lines
Hi Jonathan, all,
I wonder how links in sources work.
Documentation/userspace-api/check_exec.rsthas:
samples/check-exec/inc.c_ example.There's this bit at the end of
check_exec.rstthat defines the link:
Quoted 7 lines
Quoted 5 lines
..
_samples/check-exec/inc.c:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/samples/check-exec/inc.cThe 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
...
Quoted 22 lines · Petr Vorel
Quoted 11 lines
Quoted 10 lines · Petr Vorel
Quoted 7 lines
Hi Jonathan, all,
I wonder how links in sources work.
Documentation/userspace-api/check_exec.rsthas:
samples/check-exec/inc.c_ example.There's this bit at the end of
check_exec.rstthat defines the link:Quoted 7 lines
Quoted 5 lines
..
_samples/check-exec/inc.c:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/samples/check-exec/inc.cThe 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]
Quoted 7 lines
- commit
75069f2b5bfb("vfs: renumberFMODE_NONOTIFYand add to uniqueness check")
- commit12ed2e36c98a("fanotify:FMODE_NONOTIFYand__O_SYNCin sparc conflict")
- commitbb458c644a59("Safer ABI forO_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.
Quoted 7 lines
Kind regards,
Petr[1] https://git.kernel.org/torvalds/c/75069f2b5bfb
[2] https://docs.kernel.org/process/adding-syscalls.html#references-and-sources
...
Signature · 1 line
Jani Nikula, Intel