linux.git/Documentation/doc-guide, branch v6.6.131 Clone of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git Documentation: doc-guide: use '%' constant indicator in Return: examples 2023-07-14T19:16:59+00:00 Randy Dunlap rdunlap@infradead.org 2023-07-03T23:20:30+00:00 c15ec3d1a287698830798111ede1b7ae0bfef7f6 Use the 'constant' indicator '%' in the examples for the Return: values syntax. This can help encourage people to use it. Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Suggested-by: Steven Rostedt <rostedt@goodmis.org> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Link: https://lore.kernel.org/lkml/20221121154358.36856ca6@gandalf.local.home/ Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20230703232030.8223-1-rdunlap@infradead.org 
Use the 'constant' indicator '%' in the examples for the
Return: values syntax. This can help encourage people to use it.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Suggested-by: Steven Rostedt <rostedt@goodmis.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/lkml/20221121154358.36856ca6@gandalf.local.home/
Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20230703232030.8223-1-rdunlap@infradead.org
docs/doc-guide: Clarify how to write tables 2023-06-09T07:57:56+00:00 Joe Stringer joe@isovalent.com 2023-04-24T17:18:50+00:00 35d4a3c67eb5fe786e93e06df103fc3f181eaf07 Prior to this commit, the kernel docs writing guide spent over a page describing exactly how *not* to write tables into the kernel docs, without providing a example about the desired format. This patch provides a positive example first in the guide so that it's harder to miss, then leaves the existing less desirable approach below for contributors to follow if they have some stronger justification for why to use that approach. Signed-off-by: Joe Stringer <joe@isovalent.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/20230424171850.3612317-1-joe@isovalent.com Signed-off-by: Jonathan Corbet <corbet@lwn.net> 
Prior to this commit, the kernel docs writing guide spent over a page
describing exactly how *not* to write tables into the kernel docs,
without providing a example about the desired format.

This patch provides a positive example first in the guide so that it's
harder to miss, then leaves the existing less desirable approach below
for contributors to follow if they have some stronger justification for
why to use that approach.

Signed-off-by: Joe Stringer <joe@isovalent.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20230424171850.3612317-1-joe@isovalent.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Merge branch 'alabaster-rb' into docs-mw 2022-10-18T22:29:50+00:00 Jonathan Corbet corbet@lwn.net 2022-10-18T22:29:50+00:00 554d4389166f26765cc24f0723aee2642fcc3c26 For a long time we have rejoiced that our HTML output from Sphinx is far better than what we got from the old DocBook toolchain. But it still leaves a lot to be desired; the following is an attempt to improve the situation somewhat. Sphinx has a theming mechanism for HTML rendering. Since the kernel's adoption of Sphinx, we have been using the "Read The Docs" theme — a choice made in a bit of a hurry to have *something* while figuring out the rest. RTD is OK, but it is not hugely attractive, requires the installation of an extra package, and does not observe all of the Sphinx configuration parameters. Among other things, that makes it hard to put reasonable contents into the left column in the HTML output. The Alabaster theme is the default for Sphinx installations, and is bundled with Sphinx itself. It has (IMO) nicer output and gives us the control that we need. So: switch to Alabaster. Additional patches adjust the documentation and remove the RTD references from scripts/sphinx-pre-install. The penultimate patch changes the way that kerneldoc declarations are rendered to (IMO) improve readability. That requires some changes to kernel-doc to output a new container block and some CSS tweaks to improve things overall. It should be noted that I have a long history of inflicting ugly web designs on the net; this work is a start, but I think we could do far better yet. It would be great if somebody who actually enjoys working with CSS and such would help to improve what we have. 
For a long time we have rejoiced that our HTML output from Sphinx is far
better than what we got from the old DocBook toolchain.  But it still
leaves a lot to be desired; the following is an attempt to improve the
situation somewhat.

Sphinx has a theming mechanism for HTML rendering.  Since the kernel's
adoption of Sphinx, we have been using the "Read The Docs" theme — a choice
made in a bit of a hurry to have *something* while figuring out the rest.
RTD is OK, but it is not hugely attractive, requires the installation of an
extra package, and does not observe all of the Sphinx configuration
parameters.  Among other things, that makes it hard to put reasonable
contents into the left column in the HTML output.

The Alabaster theme is the default for Sphinx installations, and is bundled
with Sphinx itself.  It has (IMO) nicer output and gives us the control
that we need.

So: switch to Alabaster.  Additional patches adjust the documentation and
remove the RTD references from scripts/sphinx-pre-install.

The penultimate patch changes the way that kerneldoc declarations are
rendered to (IMO) improve readability.  That requires some changes to
kernel-doc to output a new container block and some CSS tweaks to improve
things overall.

It should be noted that I have a long history of inflicting ugly web
designs on the net; this work is a start, but I think we could do far
better yet.  It would be great if somebody who actually enjoys working with
CSS and such would help to improve what we have.
docs: update sphinx.rst to reflect the default theme change 2022-10-13T17:14:36+00:00 Jonathan Corbet corbet@lwn.net 2022-09-27T16:41:15+00:00 26d797ffc1c06f05ccc06f70977ebe386d628f14 We don't default to Read The Docs anymore; update the docs to match. Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> 
We don't default to Read The Docs anymore; update the docs to match.

Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Merge tag 'rust-v6.1-rc1' of https://github.com/Rust-for-Linux/linux 2022-10-03T23:39:37+00:00 Linus Torvalds torvalds@linux-foundation.org 2022-10-03T23:39:37+00:00 8aebac82933ff1a7c8eede18cab11e1115e2062b Pull Rust introductory support from Kees Cook: "The tree has a recent base, but has fundamentally been in linux-next for a year and a half[1]. It's been updated based on feedback from the Kernel Maintainer's Summit, and to gain recent Reviewed-by: tags. Miguel is the primary maintainer, with me helping where needed/wanted. Our plan is for the tree to switch to the standard non-rebasing practice once this initial infrastructure series lands. The contents are the absolute minimum to get Rust code building in the kernel, with many more interfaces[2] (and drivers - NVMe[3], 9p[4], M1 GPU[5]) on the way. The initial support of Rust-for-Linux comes in roughly 4 areas: - Kernel internals (kallsyms expansion for Rust symbols, %pA format) - Kbuild infrastructure (Rust build rules and support scripts) - Rust crates and bindings for initial minimum viable build - Rust kernel documentation and samples Rust support has been in linux-next for a year and a half now, and the short log doesn't do justice to the number of people who have contributed both to the Linux kernel side but also to the upstream Rust side to support the kernel's needs. Thanks to these 173 people, and many more, who have been involved in all kinds of ways: Miguel Ojeda, Wedson Almeida Filho, Alex Gaynor, Boqun Feng, Gary Guo, Björn Roy Baron, Andreas Hindborg, Adam Bratschi-Kaye, Benno Lossin, Maciej Falkowski, Finn Behrens, Sven Van Asbroeck, Asahi Lina, FUJITA Tomonori, John Baublitz, Wei Liu, Geoffrey Thomas, Philip Herron, Arthur Cohen, David Faust, Antoni Boucher, Philip Li, Yujie Liu, Jonathan Corbet, Greg Kroah-Hartman, Paul E. McKenney, Josh Triplett, Kent Overstreet, David Gow, Alice Ryhl, Robin Randhawa, Kees Cook, Nick Desaulniers, Matthew Wilcox, Linus Walleij, Joe Perches, Michael Ellerman, Petr Mladek, Masahiro Yamada, Arnaldo Carvalho de Melo, Andrii Nakryiko, Konstantin Shelekhin, Rasmus Villemoes, Konstantin Ryabitsev, Stephen Rothwell, Andy Shevchenko, Sergey Senozhatsky, John Paul Adrian Glaubitz, David Laight, Nathan Chancellor, Jonathan Cameron, Daniel Latypov, Shuah Khan, Brendan Higgins, Julia Lawall, Laurent Pinchart, Geert Uytterhoeven, Akira Yokosawa, Pavel Machek, David S. Miller, John Hawley, James Bottomley, Arnd Bergmann, Christian Brauner, Dan Robertson, Nicholas Piggin, Zhouyi Zhou, Elena Zannoni, Jose E. Marchesi, Leon Romanovsky, Will Deacon, Richard Weinberger, Randy Dunlap, Paolo Bonzini, Roland Dreier, Mark Brown, Sasha Levin, Ted Ts'o, Steven Rostedt, Jarkko Sakkinen, Michal Kubecek, Marco Elver, Al Viro, Keith Busch, Johannes Berg, Jan Kara, David Sterba, Connor Kuehl, Andy Lutomirski, Andrew Lunn, Alexandre Belloni, Peter Zijlstra, Russell King, Eric W. Biederman, Willy Tarreau, Christoph Hellwig, Emilio Cobos Álvarez, Christian Poveda, Mark Rousskov, John Ericson, TennyZhuang, Xuanwo, Daniel Paoliello, Manish Goregaokar, comex, Josh Stone, Stephan Sokolow, Philipp Krones, Guillaume Gomez, Joshua Nelson, Mats Larsen, Marc Poulhiès, Samantha Miller, Esteban Blanc, Martin Schmidt, Martin Rodriguez Reboredo, Daniel Xu, Viresh Kumar, Bartosz Golaszewski, Vegard Nossum, Milan Landaverde, Dariusz Sosnowski, Yuki Okushi, Matthew Bakhtiari, Wu XiangCheng, Tiago Lam, Boris-Chengbiao Zhou, Sumera Priyadarsini, Viktor Garske, Niklas Mohrin, Nándor István Krácser, Morgan Bartlett, Miguel Cano, Léo Lanteri Thauvin, Julian Merkle, Andreas Reindl, Jiapeng Chong, Fox Chen, Douglas Su, Antonio Terceiro, SeongJae Park, Sergio González Collado, Ngo Iok Ui (Wu Yu Wei), Joshua Abraham, Milan, Daniel Kolsoi, ahomescu, Manas, Luis Gerhorst, Li Hongyu, Philipp Gesang, Russell Currey, Jalil David Salamé Messina, Jon Olson, Raghvender, Angelos, Kaviraj Kanagaraj, Paul Römer, Sladyn Nunes, Mauro Baladés, Hsiang-Cheng Yang, Abhik Jain, Hongyu Li, Sean Nash, Yuheng Su, Peng Hao, Anhad Singh, Roel Kluin, Sara Saa, Geert Stappers, Garrett LeSage, IFo Hancroft, and Linus Torvalds" Link: https://lwn.net/Articles/849849/ [1] Link: https://github.com/Rust-for-Linux/linux/commits/rust [2] Link: https://github.com/metaspace/rust-linux/commit/d88c3744d6cbdf11767e08bad56cbfb67c4c96d0 [3] Link: https://github.com/wedsonaf/linux/commit/9367032607f7670de0ba1537cf09ab0f4365a338 [4] Link: https://github.com/AsahiLinux/linux/commits/gpu/rust-wip [5] * tag 'rust-v6.1-rc1' of https://github.com/Rust-for-Linux/linux: (27 commits) MAINTAINERS: Rust samples: add first Rust examples x86: enable initial Rust support docs: add Rust documentation Kbuild: add Rust support rust: add `.rustfmt.toml` scripts: add `is_rust_module.sh` scripts: add `rust_is_available.sh` scripts: add `generate_rust_target.rs` scripts: add `generate_rust_analyzer.py` scripts: decode_stacktrace: demangle Rust symbols scripts: checkpatch: enable language-independent checks for Rust scripts: checkpatch: diagnose uses of `%pA` in the C side as errors vsprintf: add new `%pA` format specifier rust: export generated symbols rust: add `kernel` crate rust: add `bindings` crate rust: add `macros` crate rust: add `compiler_builtins` crate rust: adapt `alloc` crate to the kernel ... 
Pull Rust introductory support from Kees Cook:
 "The tree has a recent base, but has fundamentally been in linux-next
  for a year and a half[1]. It's been updated based on feedback from the
  Kernel Maintainer's Summit, and to gain recent Reviewed-by: tags.

  Miguel is the primary maintainer, with me helping where needed/wanted.
  Our plan is for the tree to switch to the standard non-rebasing
  practice once this initial infrastructure series lands.

  The contents are the absolute minimum to get Rust code building in the
  kernel, with many more interfaces[2] (and drivers - NVMe[3], 9p[4], M1
  GPU[5]) on the way.

  The initial support of Rust-for-Linux comes in roughly 4 areas:

   - Kernel internals (kallsyms expansion for Rust symbols, %pA format)

   - Kbuild infrastructure (Rust build rules and support scripts)

   - Rust crates and bindings for initial minimum viable build

   - Rust kernel documentation and samples

  Rust support has been in linux-next for a year and a half now, and the
  short log doesn't do justice to the number of people who have
  contributed both to the Linux kernel side but also to the upstream
  Rust side to support the kernel's needs. Thanks to these 173 people,
  and many more, who have been involved in all kinds of ways:

  Miguel Ojeda, Wedson Almeida Filho, Alex Gaynor, Boqun Feng, Gary Guo,
  Björn Roy Baron, Andreas Hindborg, Adam Bratschi-Kaye, Benno Lossin,
  Maciej Falkowski, Finn Behrens, Sven Van Asbroeck, Asahi Lina, FUJITA
  Tomonori, John Baublitz, Wei Liu, Geoffrey Thomas, Philip Herron,
  Arthur Cohen, David Faust, Antoni Boucher, Philip Li, Yujie Liu,
  Jonathan Corbet, Greg Kroah-Hartman, Paul E. McKenney, Josh Triplett,
  Kent Overstreet, David Gow, Alice Ryhl, Robin Randhawa, Kees Cook,
  Nick Desaulniers, Matthew Wilcox, Linus Walleij, Joe Perches, Michael
  Ellerman, Petr Mladek, Masahiro Yamada, Arnaldo Carvalho de Melo,
  Andrii Nakryiko, Konstantin Shelekhin, Rasmus Villemoes, Konstantin
  Ryabitsev, Stephen Rothwell, Andy Shevchenko, Sergey Senozhatsky, John
  Paul Adrian Glaubitz, David Laight, Nathan Chancellor, Jonathan
  Cameron, Daniel Latypov, Shuah Khan, Brendan Higgins, Julia Lawall,
  Laurent Pinchart, Geert Uytterhoeven, Akira Yokosawa, Pavel Machek,
  David S. Miller, John Hawley, James Bottomley, Arnd Bergmann,
  Christian Brauner, Dan Robertson, Nicholas Piggin, Zhouyi Zhou, Elena
  Zannoni, Jose E. Marchesi, Leon Romanovsky, Will Deacon, Richard
  Weinberger, Randy Dunlap, Paolo Bonzini, Roland Dreier, Mark Brown,
  Sasha Levin, Ted Ts'o, Steven Rostedt, Jarkko Sakkinen, Michal
  Kubecek, Marco Elver, Al Viro, Keith Busch, Johannes Berg, Jan Kara,
  David Sterba, Connor Kuehl, Andy Lutomirski, Andrew Lunn, Alexandre
  Belloni, Peter Zijlstra, Russell King, Eric W. Biederman, Willy
  Tarreau, Christoph Hellwig, Emilio Cobos Álvarez, Christian Poveda,
  Mark Rousskov, John Ericson, TennyZhuang, Xuanwo, Daniel Paoliello,
  Manish Goregaokar, comex, Josh Stone, Stephan Sokolow, Philipp Krones,
  Guillaume Gomez, Joshua Nelson, Mats Larsen, Marc Poulhiès, Samantha
  Miller, Esteban Blanc, Martin Schmidt, Martin Rodriguez Reboredo,
  Daniel Xu, Viresh Kumar, Bartosz Golaszewski, Vegard Nossum, Milan
  Landaverde, Dariusz Sosnowski, Yuki Okushi, Matthew Bakhtiari, Wu
  XiangCheng, Tiago Lam, Boris-Chengbiao Zhou, Sumera Priyadarsini,
  Viktor Garske, Niklas Mohrin, Nándor István Krácser, Morgan Bartlett,
  Miguel Cano, Léo Lanteri Thauvin, Julian Merkle, Andreas Reindl,
  Jiapeng Chong, Fox Chen, Douglas Su, Antonio Terceiro, SeongJae Park,
  Sergio González Collado, Ngo Iok Ui (Wu Yu Wei), Joshua Abraham,
  Milan, Daniel Kolsoi, ahomescu, Manas, Luis Gerhorst, Li Hongyu,
  Philipp Gesang, Russell Currey, Jalil David Salamé Messina, Jon Olson,
  Raghvender, Angelos, Kaviraj Kanagaraj, Paul Römer, Sladyn Nunes,
  Mauro Baladés, Hsiang-Cheng Yang, Abhik Jain, Hongyu Li, Sean Nash,
  Yuheng Su, Peng Hao, Anhad Singh, Roel Kluin, Sara Saa, Geert
  Stappers, Garrett LeSage, IFo Hancroft, and Linus Torvalds"

Link: https://lwn.net/Articles/849849/ [1]
Link: https://github.com/Rust-for-Linux/linux/commits/rust [2]
Link: https://github.com/metaspace/rust-linux/commit/d88c3744d6cbdf11767e08bad56cbfb67c4c96d0 [3]
Link: https://github.com/wedsonaf/linux/commit/9367032607f7670de0ba1537cf09ab0f4365a338 [4]
Link: https://github.com/AsahiLinux/linux/commits/gpu/rust-wip [5]

* tag 'rust-v6.1-rc1' of https://github.com/Rust-for-Linux/linux: (27 commits)
  MAINTAINERS: Rust
  samples: add first Rust examples
  x86: enable initial Rust support
  docs: add Rust documentation
  Kbuild: add Rust support
  rust: add `.rustfmt.toml`
  scripts: add `is_rust_module.sh`
  scripts: add `rust_is_available.sh`
  scripts: add `generate_rust_target.rs`
  scripts: add `generate_rust_analyzer.py`
  scripts: decode_stacktrace: demangle Rust symbols
  scripts: checkpatch: enable language-independent checks for Rust
  scripts: checkpatch: diagnose uses of `%pA` in the C side as errors
  vsprintf: add new `%pA` format specifier
  rust: export generated symbols
  rust: add `kernel` crate
  rust: add `bindings` crate
  rust: add `macros` crate
  rust: add `compiler_builtins` crate
  rust: adapt `alloc` crate to the kernel
  ...
docs/doc-guide: Add documentation on SPHINX_IMGMATH 2022-09-29T19:13:45+00:00 Akira Yokosawa akiyks@gmail.com 2022-09-16T10:08:05+00:00 679b4bc25fc7b5b742622eb760211f2b5b1dc4db Now that building html docs with math expressions does not need texlive packages, remove the note on the requirement in the "Sphinx Install" section. Instead, add sections of "Math Expressions in HTML" and "Choice of Math Renderer". Describe the effect of setting SPHINX_IMGMATH in the latter section. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/a67e3279-6bc7-ee2c-2b49-9275252460b0@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net> 
Now that building html docs with math expressions does not need texlive
packages, remove the note on the requirement in the "Sphinx Install"
section.

Instead, add sections of "Math Expressions in HTML" and "Choice of Math
Renderer".
Describe the effect of setting SPHINX_IMGMATH in the latter section.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/a67e3279-6bc7-ee2c-2b49-9275252460b0@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
docs: add Rust documentation 2022-09-28T07:02:45+00:00 Miguel Ojeda ojeda@kernel.org 2021-07-03T15:23:16+00:00 d07479b211b7a86c93883c74b8f9b1e33d06e262 Most of the documentation for Rust is written within the source code itself, as it is idiomatic for Rust projects. This applies to both the shared infrastructure at `rust/` as well as any other Rust module (e.g. drivers) written across the kernel. However, these documents contain general information that does not fit particularly well in the source code, like the Quick Start guide. It also contains a few other small changes elsewhere in the documentation folder. Reviewed-by: Kees Cook <keescook@chromium.org> Co-developed-by: Alex Gaynor <alex.gaynor@gmail.com> Signed-off-by: Alex Gaynor <alex.gaynor@gmail.com> Co-developed-by: Finn Behrens <me@kloenk.de> Signed-off-by: Finn Behrens <me@kloenk.de> Co-developed-by: Adam Bratschi-Kaye <ark.email@gmail.com> Signed-off-by: Adam Bratschi-Kaye <ark.email@gmail.com> Co-developed-by: Wedson Almeida Filho <wedsonaf@google.com> Signed-off-by: Wedson Almeida Filho <wedsonaf@google.com> Co-developed-by: Michael Ellerman <mpe@ellerman.id.au> Signed-off-by: Michael Ellerman <mpe@ellerman.id.au> Co-developed-by: Sven Van Asbroeck <thesven73@gmail.com> Signed-off-by: Sven Van Asbroeck <thesven73@gmail.com> Co-developed-by: Wu XiangCheng <bobwxc@email.cn> Signed-off-by: Wu XiangCheng <bobwxc@email.cn> Co-developed-by: Gary Guo <gary@garyguo.net> Signed-off-by: Gary Guo <gary@garyguo.net> Co-developed-by: Boris-Chengbiao Zhou <bobo1239@web.de> Signed-off-by: Boris-Chengbiao Zhou <bobo1239@web.de> Co-developed-by: Yuki Okushi <jtitor@2k36.org> Signed-off-by: Yuki Okushi <jtitor@2k36.org> Co-developed-by: Wei Liu <wei.liu@kernel.org> Signed-off-by: Wei Liu <wei.liu@kernel.org> Co-developed-by: Daniel Xu <dxu@dxuuu.xyz> Signed-off-by: Daniel Xu <dxu@dxuuu.xyz> Co-developed-by: Julian Merkle <me@jvmerkle.de> Signed-off-by: Julian Merkle <me@jvmerkle.de> Signed-off-by: Miguel Ojeda <ojeda@kernel.org> 
Most of the documentation for Rust is written within the source code
itself, as it is idiomatic for Rust projects. This applies to both
the shared infrastructure at `rust/` as well as any other Rust module
(e.g. drivers) written across the kernel.

However, these documents contain general information that does not
fit particularly well in the source code, like the Quick Start guide.

It also contains a few other small changes elsewhere in the
documentation folder.

Reviewed-by: Kees Cook <keescook@chromium.org>
Co-developed-by: Alex Gaynor <alex.gaynor@gmail.com>
Signed-off-by: Alex Gaynor <alex.gaynor@gmail.com>
Co-developed-by: Finn Behrens <me@kloenk.de>
Signed-off-by: Finn Behrens <me@kloenk.de>
Co-developed-by: Adam Bratschi-Kaye <ark.email@gmail.com>
Signed-off-by: Adam Bratschi-Kaye <ark.email@gmail.com>
Co-developed-by: Wedson Almeida Filho <wedsonaf@google.com>
Signed-off-by: Wedson Almeida Filho <wedsonaf@google.com>
Co-developed-by: Michael Ellerman <mpe@ellerman.id.au>
Signed-off-by: Michael Ellerman <mpe@ellerman.id.au>
Co-developed-by: Sven Van Asbroeck <thesven73@gmail.com>
Signed-off-by: Sven Van Asbroeck <thesven73@gmail.com>
Co-developed-by: Wu XiangCheng <bobwxc@email.cn>
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Co-developed-by: Gary Guo <gary@garyguo.net>
Signed-off-by: Gary Guo <gary@garyguo.net>
Co-developed-by: Boris-Chengbiao Zhou <bobo1239@web.de>
Signed-off-by: Boris-Chengbiao Zhou <bobo1239@web.de>
Co-developed-by: Yuki Okushi <jtitor@2k36.org>
Signed-off-by: Yuki Okushi <jtitor@2k36.org>
Co-developed-by: Wei Liu <wei.liu@kernel.org>
Signed-off-by: Wei Liu <wei.liu@kernel.org>
Co-developed-by: Daniel Xu <dxu@dxuuu.xyz>
Signed-off-by: Daniel Xu <dxu@dxuuu.xyz>
Co-developed-by: Julian Merkle <me@jvmerkle.de>
Signed-off-by: Julian Merkle <me@jvmerkle.de>
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
docs/doc-guide: Mention make variable SPHINXDIRS 2022-06-30T18:23:38+00:00 Akira Yokosawa akiyks@gmail.com 2022-06-24T21:58:09+00:00 4d627ef12b409fd149226617180f1cc6088bbf12 SPHINXDIRS is useful when you want to test build only those documents affected by your changes. Mention it in the "Sphinx Build" section. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Maciej W. Rozycki <macro@orcam.me.uk> Link: https://lore.kernel.org/r/50d6f0bc-030d-9529-0665-e2b3e7c792d8@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net> 
SPHINXDIRS is useful when you want to test build only those
documents affected by your changes.

Mention it in the "Sphinx Build" section.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Maciej W. Rozycki <macro@orcam.me.uk>
Link: https://lore.kernel.org/r/50d6f0bc-030d-9529-0665-e2b3e7c792d8@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
docs/doc-guide: Put meta title for kernel-doc HTML page 2022-06-27T22:24:40+00:00 Akira Yokosawa akiyks@gmail.com 2022-06-09T13:28:40+00:00 5372de4e4545dead978c53d9c03b7aee12d0f94d kernel-doc.rst has two 1st level section titles of "Writing kernel-doc comments" and "Including kernel-doc comments". Therefore, rather than using the first one, put a meta title of "Kernel-doc comments" for the title of the resulting HTML page by using the "title" directive. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/15636c13-7fa2-f973-6d3d-361222b839ef@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net> 
kernel-doc.rst has two 1st level section titles of "Writing
kernel-doc comments" and "Including kernel-doc comments".

Therefore, rather than using the first one, put a meta title
of "Kernel-doc comments" for the title of the resulting HTML
page by using the "title" directive.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/15636c13-7fa2-f973-6d3d-361222b839ef@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
docs/doc-guide: Add footnote on Inkscape for better images in PDF documents 2022-06-27T22:24:40+00:00 Akira Yokosawa akiyks@gmail.com 2022-06-09T13:23:27+00:00 7c43214dddfddbb7fd2dac9bf543a056b34ce58c With kernel releases v5.18 and later, if you have Inkscape, images embedded in PDF documents are of vector graphics, not the raster images as are the case with pre-v5.18 releases. Even with pre-5.18 releases, having Inkscape would improve images converted from some of SVG files which are not fully covered by the limited capability of rsvg-convert(1) [1]. Add a footnote mentioning the expected improvements of such images. Link: https://gitlab.gnome.org/GNOME/librsvg#non-goals-of-librsvg [1] Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/81cddbde-bc28-bec1-fca4-3c8fe2df502f@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net> 
With kernel releases v5.18 and later, if you have Inkscape, images
embedded in PDF documents are of vector graphics, not the raster
images as are the case with pre-v5.18 releases.
Even with pre-5.18 releases, having Inkscape would improve images
converted from some of SVG files which are not fully covered by the
limited capability of rsvg-convert(1) [1].

Add a footnote mentioning the expected improvements of such images.

Link: https://gitlab.gnome.org/GNOME/librsvg#non-goals-of-librsvg [1]
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/81cddbde-bc28-bec1-fca4-3c8fe2df502f@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>