From 6d232c80158ae5a6fb497e0462d52c57c4459439 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 22 Aug 2016 22:02:57 -0300 Subject: [PATCH 1/7] docs-rst: kernel-doc: better output struct members Right now, for a struct, kernel-doc produces the following output: .. c:type:: struct v4l2_prio_state stores the priority states **Definition** :: struct v4l2_prio_state { atomic_t prios[4]; }; **Members** ``atomic_t prios[4]`` array with elements to store the array priorities Putting a member name in verbatim and adding a continuation line causes the LaTeX output to generate something like: item[atomic_t prios\[4\]] array with elements to store the array priorities Everything inside "item" is non-breakable, with may produce lines bigger than the column width. Also, for function members, like: int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num); It puts the name of the member at the end, like: int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read With is very confusing. The best is to highlight what really matters: the member name. is a secondary information. So, change kernel-doc, for it to produce the output on a different way: **Members** ``prios[4]`` array with elements to store the array priorities Also, as the type is not part of LaTeX "item[]", LaTeX will split it into multiple lines, if needed. So, both LaTeX/PDF and HTML outputs will look good. It should be noticed, however, that the way Sphinx LaTeX output handles things like: Foo bar is different than the HTML output. On HTML, it will produce something like: **Foo** bar While, on LaTeX, it puts both foo and bar at the same line, like: **Foo** bar Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index ba081c7636a2..d225e178aa1b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2000,7 +2000,7 @@ sub output_struct_rst(%) { ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type = $args{'parametertypes'}{$parameter}; print_lineno($parameterdesc_start_lines{$parameter_name}); - print "``$type $parameter``\n"; + print "``" . $parameter . "``\n"; output_highlight_rst($args{'parameterdescs'}{$parameter_name}); print "\n"; } From 7c142bfee6cbcd90b1847a708e22d461a1dfa38b Mon Sep 17 00:00:00 2001 From: Baoquan He Date: Wed, 24 Aug 2016 13:06:45 +0800 Subject: [PATCH 2/7] docs: kernel-parameter: Improve the description of nr_cpus and maxcpus From the old description people still can't get what's the exact difference between nr_cpus and maxcpus. Especially in kdump kernel nr_cpus is always suggested if it's implemented in the ARCH. The reason is nr_cpus is used to limit the max number of possible cpu in system, the sum of already plugged cpus and hot plug cpus can't exceed its value. However maxcpus is used to limit how many cpus are allowed to be brought up during bootup. Signed-off-by: Baoquan He Signed-off-by: Jonathan Corbet --- Documentation/kernel-parameters.txt | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 20557efa8bce..1fa28092ec00 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -2161,10 +2161,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. than or equal to this physical address is ignored. maxcpus= [SMP] Maximum number of processors that an SMP kernel - should make use of. maxcpus=n : n >= 0 limits the - kernel to using 'n' processors. n=0 is a special case, - it is equivalent to "nosmp", which also disables - the IO APIC. + will bring up during bootup. maxcpus=n : n >= 0 limits + the kernel to bring up 'n' processors. Surely after + bootup you can bring up the other plugged cpu by executing + "echo 1 > /sys/devices/system/cpu/cpuX/online". So maxcpus + only takes effect during system bootup. + While n=0 is a special case, it is equivalent to "nosmp", + which also disables the IO APIC. max_loop= [LOOP] The number of loop block devices that get (loop.max_loop) unconditionally pre-created at init time. The default @@ -2773,9 +2776,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nr_cpus= [SMP] Maximum number of processors that an SMP kernel could support. nr_cpus=n : n >= 1 limits the kernel to - supporting 'n' processors. Later in runtime you can not - use hotplug cpu feature to put more cpu back to online. - just like you compile the kernel NR_CPUS=n + support 'n' processors. It could be larger than the + number of already plugged CPU during bootup, later in + runtime you can physically add extra cpu until it reaches + n. So during boot up some boot time memory for per-cpu + variables need be pre-allocated for later physical cpu + hot plugging. nr_uarts= [SERIAL] maximum number of UARTs to be registered. From d37c43ce1975c1c3f28064bf3ebd2876e177bad8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 30 Aug 2016 20:20:57 -0300 Subject: [PATCH 3/7] docs-rst: improve typedef parser Improve the parser to handle typedefs like: typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle); Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index d225e178aa1b..ad6d4e495f3f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2190,7 +2190,9 @@ sub dump_typedef($$) { $x =~ s@/\*.*?\*/@@gos; # strip comments. # Parse function prototypes - if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) { + if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ || + $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) { + # Function typedefs $return_type = $1; $declaration_name = $2; From 82801d065b4915d030e7f63212d146a75042aa91 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 30 Aug 2016 20:20:58 -0300 Subject: [PATCH 4/7] docs-rst: kernel-doc: fix typedef output in RST format When using a typedef function like this one: typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle); The Sphinx C domain expects it to create a c:type: reference, as that's the way it creates the type references when parsing a c:function:: declaration. So, a declaration like: .. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle) Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`. So, when outputting such typedefs in RST format, we need to handle this special case, as otherwise it will produce those warnings: ./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc ./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc ./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc So, change the kernel-doc script to produce a RST output for the above typedef as: .. c:type:: v4l2_check_dv_timings_fnc **Typedef**: timings check callback **Syntax** ``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);`` Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index ad6d4e495f3f..301bf874cac8 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1831,13 +1831,22 @@ sub output_function_rst(%) { my %args = %{$_[0]}; my ($parameter, $section); my $oldprefix = $lineprefix; - my $start; + my $start = ""; - print ".. c:function:: "; - if ($args{'functiontype'} ne "") { - $start = $args{'functiontype'} . " " . $args{'function'} . " ("; + if ($args{'typedef'}) { + print ".. c:type:: ". $args{'function'} . "\n\n"; + print_lineno($declaration_start_line); + print " **Typedef**: "; + $lineprefix = ""; + output_highlight_rst($args{'purpose'}); + $start = "\n\n**Syntax**\n\n ``"; } else { - $start = $args{'function'} . " ("; + print ".. c:function:: "; + } + if ($args{'functiontype'} ne "") { + $start .= $args{'functiontype'} . " " . $args{'function'} . " ("; + } else { + $start .= $args{'function'} . " ("; } print $start; @@ -1856,11 +1865,15 @@ sub output_function_rst(%) { print $type . " " . $parameter; } } - print ")\n\n"; - print_lineno($declaration_start_line); - $lineprefix = " "; - output_highlight_rst($args{'purpose'}); - print "\n"; + if ($args{'typedef'}) { + print ");``\n\n"; + } else { + print ")\n\n"; + print_lineno($declaration_start_line); + $lineprefix = " "; + output_highlight_rst($args{'purpose'}); + print "\n"; + } print "**Parameters**\n\n"; $lineprefix = " "; @@ -2203,6 +2216,7 @@ sub dump_typedef($$) { output_declaration($declaration_name, 'function', {'function' => $declaration_name, + 'typedef' => 1, 'module' => $modulename, 'functiontype' => $return_type, 'parameterlist' => \@parameterlist, From b62b9d81a06f60ae4ad5f7a9c969f5b9680e2829 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 24 Aug 2016 15:35:24 +0200 Subject: [PATCH 5/7] docs: sphinx-extensions: add metadata parallel-safe The setup() function of a Sphinx-extension can return a dictionary. This is treated by Sphinx as metadata of the extension [1]. With metadata "parallel_read_safe = True" a extension is marked as save for "parallel reading of source". This is needed if you want build in parallel with N processes. E.g.: make SPHINXOPTS=-j4 htmldocs will no longer log warnings like: WARNING: the foobar extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit. Add metadata to extensions: * kernel-doc * flat-table * kernel-include [1] http://www.sphinx-doc.org/en/stable/extdev/#extension-metadata Signed-off-by: Markus Heiser Tested-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/sphinx/kernel-doc.py | 8 ++++++++ Documentation/sphinx/kernel_include.py | 7 +++++++ Documentation/sphinx/rstFlatTable.py | 6 ++++++ 3 files changed, 21 insertions(+) mode change 100644 => 100755 Documentation/sphinx/rstFlatTable.py diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py index f6920c0af6ee..d15e07f36881 100644 --- a/Documentation/sphinx/kernel-doc.py +++ b/Documentation/sphinx/kernel-doc.py @@ -39,6 +39,8 @@ from docutils.parsers.rst import directives from sphinx.util.compat import Directive from sphinx.ext.autodoc import AutodocReporter +__version__ = '1.0' + class KernelDocDirective(Directive): """Extract kernel-doc comments from the specified file""" required_argument = 1 @@ -139,3 +141,9 @@ def setup(app): app.add_config_value('kerneldoc_verbosity', 1, 'env') app.add_directive('kernel-doc', KernelDocDirective) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index db5738238733..f523aa68a36b 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -39,11 +39,18 @@ from docutils.parsers.rst import directives from docutils.parsers.rst.directives.body import CodeBlock, NumberLines from docutils.parsers.rst.directives.misc import Include +__version__ = '1.0' + # ============================================================================== def setup(app): # ============================================================================== app.add_directive("kernel-include", KernelInclude) + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) # ============================================================================== class KernelInclude(Include): diff --git a/Documentation/sphinx/rstFlatTable.py b/Documentation/sphinx/rstFlatTable.py old mode 100644 new mode 100755 index 26db852e3c74..55f275793028 --- a/Documentation/sphinx/rstFlatTable.py +++ b/Documentation/sphinx/rstFlatTable.py @@ -73,6 +73,12 @@ def setup(app): roles.register_local_role('cspan', c_span) roles.register_local_role('rspan', r_span) + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) + # ============================================================================== def c_span(name, rawtext, text, lineno, inliner, options=None, content=None): # ============================================================================== From cd21379b169827bb4314b72641511593ed9ba2b6 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 24 Aug 2016 17:36:14 +0200 Subject: [PATCH 6/7] doc-rst: generic way to build PDF of sub-folders This extends the method to build only sub-folders to the targets "latexdocs" and "pdfdocs". To do so, a conf.py in the sub-folder is required, where the latex_documents of the sub-folder are defined. E.g. to build only gpu's PDF add the following to the Documentation/gpu/conf.py:: +latex_documents = [ + ("index", "gpu.tex", "Linux GPU Driver Developer's Guide", + "The kernel development community", "manual"), +] and run: make SPHINXDIRS=gpu pdfdocs Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/Makefile.sphinx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index 894cfaa41f55..92deea30b183 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -71,12 +71,12 @@ ifeq ($(HAVE_PDFLATEX),0) $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX - @$(call loop_cmd,sphinx,latex,.,latex,.) + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) endif # HAVE_PDFLATEX pdfdocs: latexdocs ifneq ($(HAVE_PDFLATEX),0) - $(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/latex + $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex) endif # HAVE_PDFLATEX epubdocs: From 951499710be258b85c135ee1f7ebe5f7a4b7ac91 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 24 Aug 2016 17:36:15 +0200 Subject: [PATCH 7/7] doc-rst: define PDF's of the media folder To build only the PDF of the media folder run:: make SPHINXDIRS=media pdfdocs Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/media/conf.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Documentation/media/conf.py b/Documentation/media/conf.py index 77cb2bbd9461..bef927bc4659 100644 --- a/Documentation/media/conf.py +++ b/Documentation/media/conf.py @@ -3,3 +3,8 @@ project = 'Linux Media Subsystem Documentation' tags.add("subproject") + +latex_documents = [ + ('index', 'media.tex', 'Linux Media Subsystem Documentation', + 'The kernel development community', 'manual'), +]