linux.git/Documentation/Makefile, branch v6.8

doc/netlink: Regenerate netlink .rst files if ynl-gen-rst changes

2023-12-18T22:39:44+00:00

Add ynl-gen-rst.py to the dependencies for the netlink .rst files in the
doc Makefile so that the docs get regenerated if the ynl-gen-rst.py
script is modified. Use $(Q) to honour V=1 in the rules that run
ynl-gen-rst.py

Reviewed-by: Jakub Kicinski 
Reviewed-by: Breno Leitao 
Signed-off-by: Donald Hunter 
Link: https://lore.kernel.org/r/20231215093720.18774-10-donald.hunter@gmail.com
Signed-off-by: Jakub Kicinski

Documentation: Document each netlink family

2023-11-24T01:16:56+00:00

This is a simple script that parses the Netlink YAML spec files
(Documentation/netlink/specs/), and generates RST files to be rendered
in the Network -> Netlink Specification documentation page.

Create a python script that is invoked during 'make htmldocs', reads the
YAML specs input file and generate the correspondent RST file.

Create a new Documentation/networking/netlink_spec index page, and
reference each Netlink RST file that was processed above in this main
index.rst file.

In case of any exception during the parsing, dump the error and skip
the file.

Do not regenerate the RST files if the input files (YAML) were not
changed in-between invocations.

Suggested-by: Jakub Kicinski 
Signed-off-by: Breno Leitao 

----
Changelog:

V3:
	* Do not regenerate the RST files if the input files were not
	  changed. In order to do it, a few things changed:
	  - Rely on Makefile more to find what changed, and trigger
	    individual file processing
	  - The script parses file by file now (instead of batches)
	  - Create a new option to generate the index file

V2:
	* Moved the logic from a sphinx extension to a external script
	* Adjust some formatting as suggested by Donald Hunter and Jakub
	* Auto generating all the rsts instead of having stubs
	* Handling error gracefully
Reviewed-by: Jakub Kicinski 
Signed-off-by: David S. Miller

docs: Integrate rustdoc generation into htmldocs

2023-07-21T21:08:46+00:00

Change target `make htmldocs` to combine RST Sphinx and the generation of
Rust documentation, when support is available and .config exists.

Reviewed-by: Akira Yokosawa 
Signed-off-by: Carlos Bilbao 
Reviewed-by: Martin Rodriguez Reboredo 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20230718151534.4067460-3-carlos.bilbao@amd.com

kbuild: do not print extra logs for V=2

2023-01-22T14:43:32+00:00

Some scripts increase the verbose level when V=1, but others when
not V=0.

I think the former is correct because V=2 is not a log level but
a switch to print the reason for rebuilding.

Signed-off-by: Masahiro Yamada 
Reviewed-by: Nicolas Schier

doc: add texinfodocs and infodocs targets

2022-11-21T21:13:57+00:00

Sphinx supports generating Texinfo sources and Info documentation,
which can be navigated easily and is convenient to search (via the
indexed nodes or anchors, for example).

Signed-off-by: Maxim Cournoyer 
Link: https://lore.kernel.org/r/20221116190210.28407-2-maxim.cournoyer@gmail.com
Signed-off-by: Jonathan Corbet

docs: Makefile: Add -no-shell-escape option to LATEXOPTS

2022-02-14T19:50:17+00:00

It turns out that LaTeX enables \write18, which allows (some) shell
commands to be executed from the document source, by default.  This the
often-seen warning during a pdfdocs build:

  restricted \write18 enabled

That is a potential security problem and is entirely unnecessary; nothing
in the kernel PDF docs build needs that capability.  So disable \write18
explicitly.

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/519bd2d9-1bee-03e1-eeb4-d9883c18be0c@gmail.com
Signed-off-by: Jonathan Corbet

docs: address some text issues with css/theme support

2021-12-16T22:54:12+00:00

Fix:
- overriden ->overridden
- some whitespace issues introduced at the css/theme
  Makefile help.

Reported-by: Randy Dunlap 
Signed-off-by: Mauro Carvalho Chehab 
Reviewed-by: Randy Dunlap 
Link: https://lore.kernel.org/r/b0b166025019f7cc4f122bd789c79ba28cc2d29d.1639212812.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet

docs: Makefile: use the right path for DOCS_CSS

2021-12-16T22:54:12+00:00

When make is used with O=, the location of the css file
won't be get right:

	$ make DOCS_THEME=nature DOCS_CSS=my_css.css    O=DOCS SPHINXDIRS=x86 -j9 htmldocs
	make[1]: Entering directory '/work/lnx/next/next-2021-1210/DOCS'
	...
	cp: cannot stat 'my_css.css': No such file or directory

Fix it in a way that both relative and absolute paths will be
handled.

Reported-by: Randy Dunlap 
Signed-off-by: Mauro Carvalho Chehab 
Reviewed-by: Randy Dunlap 
Tested-by: Randy Dunlap 
Link: https://lore.kernel.org/r/cea4ff1237ae9a99bc6509ab1bf9c70acd97e265.1639212812.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet

docs: allow to pass extra DOCS_CSS themes via make

2021-12-10T21:05:55+00:00

Specially when the RTD theme is not used, it makes sense to
allow specifying extra CSS files via a make variable.

Signed-off-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/03d09bf41ad39aa0abfe2ea3c879b09aa3a0948d.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet

docs: allow selecting a Sphinx theme

2021-12-10T21:05:55+00:00

Instead of having RTD as an almost mandatory theme, allow the
user to select other themes via DOCS_THEME environment var.

There's a catch, though: as the current theme override logic is
dependent of the RTD theme, we need to move the code which
adds the CSS overrides to be inside the RTD theme logic.

Signed-off-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/bd20adabfd428fd3cd0e69c2cf146aa354932936.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet