linux-toradex.git/Documentation/kernel-hacking, branch v5.11-rc6

docs: Fix reST markup when linking to sections

2020-12-31T22:44:47+00:00

During the process of converting the documentation to reST, some links
were converted using the following wrong syntax (and sometimes using %20
instead of spaces):

   `Display text <#section-name-in-html>`__

This syntax isn't valid according to the docutils' spec [1], but more
importantly, it is specific to HTML, since it uses '#' to link to an
HTML anchor.

The right syntax would instead use a docutils hyperlink reference as the
embedded URI to point to the section [2], that is:

   `Display text `__

This syntax works in both HTML and PDF.

The LaTeX toolchain doesn't mind the HTML anchor syntax when generating
the pdf documentation (make pdfdocs), that is, the build succeeds but
the links don't work, but that syntax causes errors when trying to build
using the not-yet-merged rst2pdf:

   ValueError: format not resolved, probably missing URL scheme or undefined destination target for 'Forcing%20Quiescent%20States'

So, use the correct syntax in order to have it work in all different
output formats.

[1]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-names
[2]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases

Fixes: ccc9971e2147 ("docs: rcu: convert some articles from html to ReST")
Fixes: c8cce10a62aa ("docs: Fix the reference labels in Locking.rst")
Fixes: e548cdeffcd8 ("docs-rst: convert kernel-locking to ReST")
Fixes: 7ddedebb03b7 ("ALSA: doc: ReSTize writing-an-alsa-driver document")
Signed-off-by: Nícolas F. R. A. Prado 
Reviewed-by: Takashi Iwai 
Reviewed-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/20201228144537.135353-1-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet

docs: locking: Drop :c:func: throughout

2020-03-20T23:16:24+00:00

The kernel doc tooling knows how to do this itself so drop this markup
throughout this file to simplify.

Suggested-by: Jonathan Corbet 
Signed-off-by: Stephen Boyd 
Link: https://lore.kernel.org/r/20200318174133.160206-3-swboyd@chromium.org
Signed-off-by: Jonathan Corbet

docs: locking: Add 'need' to hardirq section

2020-03-20T23:16:19+00:00

Add the missing word to make this sentence read properly.

Signed-off-by: Stephen Boyd 
Link: https://lore.kernel.org/r/20200318174133.160206-2-swboyd@chromium.org
Signed-off-by: Jonathan Corbet

docs: prevent warnings due to autosectionlabel

2020-03-20T23:01:29+00:00

Changeset 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst")
enabled a new feature at Sphinx: it will now generate index for each
document title, plus to each chapter inside it.

There's a drawback, though: one document cannot have two sections
with the same name anymore.

A followup patch will change the logic of autosectionlabel to
avoid most creating references for every single section title,
but still we need to be able to reference the chapters inside
a document.

There are a few places where there are two chapters with the
same name. This patch renames one of the chapters, in order to
avoid symbol conflict within the same document.

PS.: as I don't speach Chinese, I had some help from a friend
(Wen Liu) at the Chinese translation for "publishing patches"
for this document:

	Documentation/translations/zh_CN/process/5.Posting.rst

Fixes: 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst")
Signed-off-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/2bffb91e4a63d41bf5fae1c23e1e8b3bba0b8806.1584716446.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet

docs: fix reference to core-api/namespaces.rst

2020-03-19T18:52:01+00:00

Fix a couple of dangling links to core-api/namespaces.rst by turning them
into proper references.  Enable the autosection extension (available since
Sphinx 1.4) to make this work.

Co-developed-by: Federico Vaga 
Fixes: fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/")
Signed-off-by: Jonathan Corbet

Documentation: kernel-hacking: hacking.rst: Change reference to document namespaces.rst to symbol-namespaces.rst

2019-12-19T16:36:23+00:00

This patch fixes the following documentation build warning:
Warning: Documentation/kernel-hacking/hacking.rst references
a file that doesn't exist: Documentation/kbuild/namespaces.rst

According to the following patch:
https://patchwork.kernel.org/patch/11178727/
(doc: move namespaces.rst from kbuild/ to core-api/)

The file namespaces.rst was moved from kbuild to core-api
and renamed to symbol-namespaces.rst.
Therefore, this patch changes the reference to the document
kbuild/namespaces.rst in hacking.rst to
core-api/symbol-namespaces.rst

Signed-off-by: Madhuparna Bhowmik 
Link: https://lore.kernel.org/r/20191204104554.9100-1-madhuparnabhowmik04@gmail.com
Signed-off-by: Jonathan Corbet

docs: Add documentation for Symbol Namespaces

2019-09-10T08:30:49+00:00

Describe using Symbol Namespaces from a perspective of a user. I.e.
module authors or subsystem maintainers.

Reviewed-by: Greg Kroah-Hartman 
Signed-off-by: Matthias Maennich 
Signed-off-by: Jessica Yu

docs: remove extra conf.py files

2019-07-17T09:57:52+00:00

Now that the latex_documents are handled automatically, we can
remove those extra conf.py files.

Signed-off-by: Mauro Carvalho Chehab

docs: locking: convert docs to ReST and rename to *.rst

2019-07-15T11:53:27+00:00

Convert the locking documents to ReST and add them to the
kernel development book where it belongs.

Most of the stuff here is just to make Sphinx to properly
parse the text file, as they're already in good shape,
not requiring massive changes in order to be parsed.

The conversion is actually:
  - add blank lines and identation in order to identify paragraphs;
  - fix tables markups;
  - add some lists markups;
  - mark literal blocks;
  - adjust title markups.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab 
Acked-by: Federico Vaga

docs: stop suggesting strlcpy

2019-06-20T20:08:49+00:00

Since strlcpy is deprecated, the documentation shouldn't suggest using
it. This patch fixes the examples to use strscpy instead. It also uses
sizeof instead of underlying constants as far as possible, to simplify
future changes to the corresponding data structures.

Signed-off-by: Stephen Kitt 
Acked-by: Kees Cook 
Acked-by: Federico Vaga 
Signed-off-by: Jonathan Corbet