This line was initially placed in {# jinja2 comments #}, but that led to an
"invalid token" complaint from spdxcheck.py. Rather than fix the script
for a usage we'll likely never see anywhere else, just switch to an HTML
comment, which spdxcheck.py thinks is fine.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add a new sidebar template that creates a more RTD-like "fisheye" view of
the current place in the document hierarchy. It is far from ideal, but
some readers may find it better for navigating through the documentation as
a whole.
Add some CSS trickery as well to make the table of contents less intrusive
when viewing the pages on a small screen.
Reviewed-by: Akira Yokosawa <akiyks@gmail.com>
Reviewed-by: David Gow <davidgow@google.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add a new section to the admin-guide with information of interest to
application developers and system integrators doing analysis of the
Linux kernel for safety critical applications.
This section will contain documents supporting analysis of kernel
interactions with applications, and key kernel subsystems expectations.
Add a new workload-tracing document to this new section.
Signed-off-by: Shefali Sharma <sshefali021@gmail.com>
Signed-off-by: Shuah Khan <skhan@linuxfoundation.org>
Link: https://lore.kernel.org/r/20230131221105.39216-1-skhan@linuxfoundation.org
[jc: tweaked the sphinx formatting a bit]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
It is enough to use a file name to cross-reference another rst document.
Jon says:
The right things will happen in the HTML output, readers of the
plain-text will know immediately where to go, and we don't have to add
the label clutter.
Drop reference markup and unnecessary labels and use plain file names.
Signed-off-by: Mike Rapoport (IBM) <rppt@kernel.org>
Link: https://lore.kernel.org/r/20230201094156.991542-4-rppt@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
It is enough to use a file name to cross-reference another rst document.
Jon says:
The right things will happen in the HTML output, readers of the
plain-text will know immediately where to go, and we don't have to add
the label clutter.
Drop reference markup and unnecessary labels and use plain file names.
Signed-off-by: Mike Rapoport (IBM) <rppt@kernel.org>
Link: https://lore.kernel.org/r/20230201094156.991542-3-rppt@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jon says:
> +See also :ref:`Page Reclaim <page_reclaim>`.
Can also just be "See also Documentation/mm/page_reclaim.rst". The
right things will happen in the HTML output, readers of the plain-text
will know immediately where to go, and we don't have to add the label
clutter.
Remove reference markup and unnecessary labes and use plain file names.
Fixes: 5d8c5e430a ("docs/mm: Physical Memory: add structure, introduction and nodes description")
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Acked-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Mike Rapoport (IBM) <rppt@kernel.org>
Link: https://lore.kernel.org/r/20230201094156.991542-2-rppt@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The canonical location for the tracefs filesystem is at /sys/kernel/tracing.
But, from Documentation/trace/ftrace.rst:
Before 4.1, all ftrace tracing control files were within the debugfs
file system, which is typically located at /sys/kernel/debug/tracing.
For backward compatibility, when mounting the debugfs file system,
the tracefs file system will be automatically mounted at:
/sys/kernel/debug/tracing
Many parts of Documentation still reference this older debugfs path, so
let's update them to avoid confusion.
Signed-off-by: Ross Zwisler <zwisler@google.com>
Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Link: https://lore.kernel.org/r/20230125213251.2013791-1-zwisler@google.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Commit 43756e347f ("scripts/kernel-doc: Add support for named variable
macro arguments") improved how named variable macro arguments are
handled, and changed how they are documented in kerneldoc comments
from "@param...", to "@param", deprecating the old syntax.
All users of the old syntax have since been converted, so this commit
finally removes support for it.
The output of "make htmldocs" is the same with and without this commit.
Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Link: https://lore.kernel.org/r/20230129150435.1510400-1-j.neuschaefer@gmx.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
In order to debug the kernel successfully with gdb you need to run
'make scripts_gdb' nowadays.
This was changed with the following commit:
Commit 67274c0834 ("scripts/gdb: delay generation of gdb
constants.py")
In order to have a complete guide for beginners this remark
should be added to the offial documentation.
Signed-off-by: Jakob Koschel <jkl820.git@gmail.com>
Link: https://lore.kernel.org/r/20230112-documentation-gdb-v2-1-292785c43dc9@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Translation for the following patches
commit da4288b95b ("scripts/check-local-export: avoid 'wait $!' for process substitution")
commit 5372de4e45 ("docs/doc-guide: Put meta title for kernel-doc HTML page")
commit 4d627ef12b ("docs/doc-guide: Mention make variable SPHINXDIRS")
commit 7c43214ddd ("docs/doc-guide: Add footnote on Inkscape for better images in PDF documents")
commit 615041d42a ("docs: kernel-docs: shorten the lengthy doc title")
commit cbf4adfd4d ("Documentation: process: Update email client instructions for Thunderbird")
commit e72b3b9810 ("maintainer-pgp-guide: minor wording tweaks")
commit ea522496af ("Documentation: process: replace outdated LTS table w/ link")
commit 93431e0607 ("Replace HTTP links with HTTPS ones: documentation")
commit e648174b53 ("Documentation: Fix spelling mistake in hacking.rst")
commit 602684adb4 ("docs: Update version number from 5.x to 6.x in README.rst")
commit 489876063f ("docs: add a man-pages link to the front page")
commit 0c7b4366f1 ("docs: Rewrite the front page")
Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
Link: https://lore.kernel.org/r/20221231130849.4675-1-federico.vaga@vaga.pv.it
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The Sphinx 2.4 release is three years old, and it is becoming increasingly
difficult to even find a system with an sufficiently archaic Python
installation that can run versions older than that. I can no longer test
changes against anything prior to 2.4.x.
Move toward raising our minimum Sphinx requirement to 2.4.x so we can
delete some older support code and claim to support a range of versions
that we can actually test.
In the absence of screams, the actual removal of support can happen later
in 2023.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Sphinx 6.0 removed the execfile_() function, which we use as part of the
configuration process. They *did* warn us... Just open-code the
functionality as is done in Sphinx itself.
Tested (using SPHINX_CONF, since this code is only executed with an
alternative config file) on various Sphinx versions from 2.5 through 6.0.
Reported-by: Martin Liška <mliska@suse.cz>
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
