linux-stable.git/Documentation/Makefile, branch v6.9

docs: Makefile: Add dependency to $(YNL_INDEX) for targets other than htmldocs

2024-03-05T18:06:43+00:00

Commit f061c9f7d058 ("Documentation: Document each netlink family")
added recipes for YAML -> RST conversion.
Then commit 7da8bdbf8f5d ("docs: Makefile: Fix make cleandocs by
deleting generated .rst files") made sure those converted .rst files
are cleaned by "make cleandocs".

However, they took care of htmldocs build only.

If one of other targets such as latexdocs or epubdocs is built
without building htmldocs, missing .rst files can cause additional
WARNINGs from sphinx-build as follow:

    ./Documentation/userspace-api/netlink/specs.rst:18: WARNING: undefined label: 'specs'
    ./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/rt_link'
    ./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/tc'
    ./Documentation/userspace-api/netlink/index.rst:21: WARNING: undefined label: 'specs'

Add dependency to $(YNL_INDEX) for other targets and allow any targets
to be built cleanly right after "make cleandocs".

Signed-off-by: Akira Yokosawa 
Cc: stable@vger.kernel.org  # v6.7
Cc: Thorsten Blum 
Cc: Breno Leitao 
Cc: Jakub Kicinski 
Cc: "David S. Miller" 
Reviwed-by: Breno Leitao 
Signed-off-by: Jonathan Corbet 
Message-ID:

docs: Makefile: Fix make cleandocs by deleting generated .rst files

2024-02-14T22:43:29+00:00

The script tools/net/ynl/ynl-gen-rst.py (YNL_TOOL) generates several .rst
files (YNL_INDEX, YNL_RST_FILES) in Documentation/networking/netlink_spec
(YNL_RST_DIR) which are not deleted by make cleandocs.

Fix make cleandocs by deleting the generated .rst files.

Signed-off-by: Thorsten Blum 
Reviewed-by: Vegard Nossum 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20240208145001.61769-1-thorsten.blum@toblux.com

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