diff options
Diffstat (limited to 'Documentation/sphinx')
| -rw-r--r-- | Documentation/sphinx/cdomain.py | 165 | ||||
| -rw-r--r-- | Documentation/sphinx/kernel-doc.py | 8 | ||||
| -rwxr-xr-x | Documentation/sphinx/kernel_include.py | 7 | ||||
| -rw-r--r-- | Documentation/sphinx/load_config.py | 32 | ||||
| -rwxr-xr-x | Documentation/sphinx/parse-headers.pl | 129 | ||||
| -rwxr-xr-x[-rw-r--r--] | Documentation/sphinx/rstFlatTable.py | 6 |
6 files changed, 288 insertions, 59 deletions
diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py new file mode 100644 index 000000000000..df0419c62096 --- /dev/null +++ b/Documentation/sphinx/cdomain.py @@ -0,0 +1,165 @@ +# -*- coding: utf-8; mode: python -*- +# pylint: disable=W0141,C0113,C0103,C0325 +u""" + cdomain + ~~~~~~~ + + Replacement for the sphinx c-domain. + + :copyright: Copyright (C) 2016 Markus Heiser + :license: GPL Version 2, June 1991 see Linux/COPYING for details. + + List of customizations: + + * Moved the *duplicate C object description* warnings for function + declarations in the nitpicky mode. See Sphinx documentation for + the config values for ``nitpick`` and ``nitpick_ignore``. + + * Add option 'name' to the "c:function:" directive. With option 'name' the + ref-name of a function can be modified. E.g.:: + + .. c:function:: int ioctl( int fd, int request ) + :name: VIDIOC_LOG_STATUS + + The func-name (e.g. ioctl) remains in the output but the ref-name changed + from 'ioctl' to 'VIDIOC_LOG_STATUS'. The function is referenced by:: + + * :c:func:`VIDIOC_LOG_STATUS` or + * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3) + + * Handle signatures of function-like macros well. Don't try to deduce + arguments types of function-like macros. + +""" + +from docutils import nodes +from docutils.parsers.rst import directives + +import sphinx +from sphinx import addnodes +from sphinx.domains.c import c_funcptr_sig_re, c_sig_re +from sphinx.domains.c import CObject as Base_CObject +from sphinx.domains.c import CDomain as Base_CDomain + +__version__ = '1.0' + +# Get Sphinx version +major, minor, patch = map(int, sphinx.__version__.split(".")) + +def setup(app): + + app.override_domain(CDomain) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) + +class CObject(Base_CObject): + + """ + Description of a C language object. + """ + option_spec = { + "name" : directives.unchanged + } + + def handle_func_like_macro(self, sig, signode): + u"""Handles signatures of function-like macros. + + If the objtype is 'function' and the the signature ``sig`` is a + function-like macro, the name of the macro is returned. Otherwise + ``False`` is returned. """ + + if not self.objtype == 'function': + return False + + m = c_funcptr_sig_re.match(sig) + if m is None: + m = c_sig_re.match(sig) + if m is None: + raise ValueError('no match') + + rettype, fullname, arglist, _const = m.groups() + arglist = arglist.strip() + if rettype or not arglist: + return False + + arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup + arglist = [a.strip() for a in arglist.split(",")] + + # has the first argument a type? + if len(arglist[0].split(" ")) > 1: + return False + + # This is a function-like macro, it's arguments are typeless! + signode += addnodes.desc_name(fullname, fullname) + paramlist = addnodes.desc_parameterlist() + signode += paramlist + + for argname in arglist: + param = addnodes.desc_parameter('', '', noemph=True) + # separate by non-breaking space in the output + param += nodes.emphasis(argname, argname) + paramlist += param + + return fullname + + def handle_signature(self, sig, signode): + """Transform a C signature into RST nodes.""" + + fullname = self.handle_func_like_macro(sig, signode) + if not fullname: + fullname = super(CObject, self).handle_signature(sig, signode) + + if "name" in self.options: + if self.objtype == 'function': + fullname = self.options["name"] + else: + # FIXME: handle :name: value of other declaration types? + pass + return fullname + + def add_target_and_index(self, name, sig, signode): + # for C API items we add a prefix since names are usually not qualified + # by a module name and so easily clash with e.g. section titles + targetname = 'c.' + name + if targetname not in self.state.document.ids: + signode['names'].append(targetname) + signode['ids'].append(targetname) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + inv = self.env.domaindata['c']['objects'] + if (name in inv and self.env.config.nitpicky): + if self.objtype == 'function': + if ('c:func', name) not in self.env.config.nitpick_ignore: + self.state_machine.reporter.warning( + 'duplicate C object description of %s, ' % name + + 'other instance in ' + self.env.doc2path(inv[name][0]), + line=self.lineno) + inv[name] = (self.env.docname, self.objtype) + + indextext = self.get_index_text(name) + if indextext: + if major == 1 and minor < 4: + # indexnode's tuple changed in 1.4 + # https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c + self.indexnode['entries'].append( + ('single', indextext, targetname, '')) + else: + self.indexnode['entries'].append( + ('single', indextext, targetname, '', None)) + +class CDomain(Base_CDomain): + + """C language domain.""" + name = 'c' + label = 'C' + directives = { + 'function': CObject, + 'member': CObject, + 'macro': CObject, + 'type': CObject, + 'var': CObject, + } 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/load_config.py b/Documentation/sphinx/load_config.py new file mode 100644 index 000000000000..301a21aa4f63 --- /dev/null +++ b/Documentation/sphinx/load_config.py @@ -0,0 +1,32 @@ +# -*- coding: utf-8; mode: python -*- +# pylint: disable=R0903, C0330, R0914, R0912, E0401 + +import os +import sys +from sphinx.util.pycompat import execfile_ + +# ------------------------------------------------------------------------------ +def loadConfig(namespace): +# ------------------------------------------------------------------------------ + + u"""Load an additional configuration file into *namespace*. + + The name of the configuration file is taken from the environment + ``SPHINX_CONF``. The external configuration file extends (or overwrites) the + configuration values from the origin ``conf.py``. With this you are able to + maintain *build themes*. """ + + config_file = os.environ.get("SPHINX_CONF", None) + if (config_file is not None + and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ): + config_file = os.path.abspath(config_file) + + if os.path.isfile(config_file): + sys.stdout.write("load additional sphinx-config: %s\n" % config_file) + config = namespace.copy() + config['__file__'] = config_file + execfile_(config_file, config) + del config['__file__'] + namespace.update(config) + else: + sys.stderr.write("WARNING: additional sphinx-config not found: %s\n" % config_file) diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl index 34bd9e2630b0..db0186a7618f 100755 --- a/Documentation/sphinx/parse-headers.pl +++ b/Documentation/sphinx/parse-headers.pl @@ -2,12 +2,18 @@ use strict; use Text::Tabs; -# Uncomment if debug is needed -#use Data::Dumper; - -# change to 1 to generate some debug prints my $debug = 0; +while ($ARGV[0] =~ m/^-(.*)/) { + my $cmd = shift @ARGV; + if ($cmd eq "--debug") { + require Data::Dumper; + $debug = 1; + next; + } + die "argument $cmd unknown"; +} + if (scalar @ARGV < 2 || scalar @ARGV > 3) { die "Usage:\n\t$0 <file in> <file out> [<exceptions file>]\n"; } @@ -51,7 +57,7 @@ while (<IN>) { $n =~ tr/A-Z/a-z/; $n =~ tr/_/-/; - $enum_symbols{$s} = $n; + $enum_symbols{$s} = "\\ :ref:`$s <$n>`\\ "; $is_enum = 0 if ($is_enum && m/\}/); next; @@ -63,7 +69,7 @@ while (<IN>) { my $n = $1; $n =~ tr/A-Z/a-z/; - $ioctls{$s} = $n; + $ioctls{$s} = "\\ :ref:`$s <$n>`\\ "; next; } @@ -73,17 +79,15 @@ while (<IN>) { $n =~ tr/A-Z/a-z/; $n =~ tr/_/-/; - $defines{$s} = $n; + $defines{$s} = "\\ :ref:`$s <$n>`\\ "; next; } - if ($ln =~ m/^\s*typedef\s+.*\s+([_\w][\w\d_]+);/) { - my $s = $1; - my $n = $1; - $n =~ tr/A-Z/a-z/; - $n =~ tr/_/-/; + if ($ln =~ m/^\s*typedef\s+([_\w][\w\d_]+)\s+(.*)\s+([_\w][\w\d_]+);/) { + my $s = $2; + my $n = $3; - $typedefs{$s} = $n; + $typedefs{$n} = "\\ :c:type:`$n <$s>`\\ "; next; } if ($ln =~ m/^\s*enum\s+([_\w][\w\d_]+)\s+\{/ @@ -91,11 +95,8 @@ while (<IN>) { || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)\s+\{/ || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)$/) { my $s = $1; - my $n = $1; - $n =~ tr/A-Z/a-z/; - $n =~ tr/_/-/; - $enums{$s} = $n; + $enums{$s} = "enum :c:type:`$s`\\ "; $is_enum = $1; next; @@ -106,11 +107,8 @@ while (<IN>) { || $ln =~ m/^\s*typedef\s*struct\s+([[_\w][\w\d_]+)$/ ) { my $s = $1; - my $n = $1; - $n =~ tr/A-Z/a-z/; - $n =~ tr/_/-/; - $structs{$s} = $n; + $structs{$s} = "struct :c:type:`$s`\\ "; next; } } @@ -123,12 +121,9 @@ close IN; my @matches = ($data =~ m/typedef\s+struct\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g, $data =~ m/typedef\s+enum\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g,); foreach my $m (@matches) { - my $s = $m; - my $n = $m; - $n =~ tr/A-Z/a-z/; - $n =~ tr/_/-/; + my $s = $m; - $typedefs{$s} = $n; + $typedefs{$s} = "\\ :c:type:`$s`\\ "; next; } @@ -136,6 +131,15 @@ foreach my $m (@matches) { # Handle exceptions, if any # +my %def_reftype = ( + "ioctl" => ":ref", + "define" => ":ref", + "symbol" => ":ref", + "typedef" => ":c:type", + "enum" => ":c:type", + "struct" => ":c:type", +); + if ($file_exceptions) { open IN, $file_exceptions or die "Can't read $file_exceptions"; while (<IN>) { @@ -169,29 +173,49 @@ if ($file_exceptions) { } # Parsers to replace a symbol + my ($type, $old, $new, $reftype); + + if (m/^replace\s+(\S+)\s+(\S+)\s+(\S+)/) { + $type = $1; + $old = $2; + $new = $3; + } else { + die "Can't parse $file_exceptions: $_"; + } + + if ($new =~ m/^\:c\:(data|func|macro|type)\:\`(.+)\`/) { + $reftype = ":c:$1"; + $new = $2; + } elsif ($new =~ m/\:ref\:\`(.+)\`/) { + $reftype = ":ref"; + $new = $1; + } else { + $reftype = $def_reftype{$type}; + } + $new = "$reftype:`$old <$new>`"; - if (m/^replace\s+ioctl\s+(\S+)\s+(\S+)/) { - $ioctls{$1} = $2 if (exists($ioctls{$1})); + if ($type eq "ioctl") { + $ioctls{$old} = $new if (exists($ioctls{$old})); next; } - if (m/^replace\s+define\s+(\S+)\s+(\S+)/) { - $defines{$1} = $2 if (exists($defines{$1})); + if ($type eq "define") { + $defines{$old} = $new if (exists($defines{$old})); next; } - if (m/^replace\s+typedef\s+(\S+)\s+(\S+)/) { - $typedefs{$1} = $2 if (exists($typedefs{$1})); + if ($type eq "symbol") { + $enum_symbols{$old} = $new if (exists($enum_symbols{$old})); next; } - if (m/^replace\s+enum\s+(\S+)\s+(\S+)/) { - $enums{$1} = $2 if (exists($enums{$1})); + if ($type eq "typedef") { + $typedefs{$old} = $new if (exists($typedefs{$old})); next; } - if (m/^replace\s+symbol\s+(\S+)\s+(\S+)/) { - $enum_symbols{$1} = $2 if (exists($enum_symbols{$1})); + if ($type eq "enum") { + $enums{$old} = $new if (exists($enums{$old})); next; } - if (m/^replace\s+struct\s+(\S+)\s+(\S+)/) { - $structs{$1} = $2 if (exists($structs{$1})); + if ($type eq "struct") { + $structs{$old} = $new if (exists($structs{$old})); next; } @@ -220,7 +244,7 @@ $data =~ s/\n\s+\n/\n\n/g; # # Add escape codes for special characters # -$data =~ s,([\_\`\*\<\>\&\\\\:\/\|]),\\$1,g; +$data =~ s,([\_\`\*\<\>\&\\\\:\/\|\%\$\#\{\}\~\^]),\\$1,g; $data =~ s,DEPRECATED,**DEPRECATED**,g; @@ -232,9 +256,7 @@ my $start_delim = "[ \n\t\(\=\*\@]"; my $end_delim = "(\\s|,|\\\\=|\\\\:|\\;|\\\)|\\}|\\{)"; foreach my $r (keys %ioctls) { - my $n = $ioctls{$r}; - - my $s = "\\ :ref:`$r <$n>`\\ "; + my $s = $ioctls{$r}; $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; @@ -244,9 +266,7 @@ foreach my $r (keys %ioctls) { } foreach my $r (keys %defines) { - my $n = $defines{$r}; - - my $s = "\\ :ref:`$r <$n>`\\ "; + my $s = $defines{$r}; $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; @@ -256,9 +276,7 @@ foreach my $r (keys %defines) { } foreach my $r (keys %enum_symbols) { - my $n = $enum_symbols{$r}; - - my $s = "\\ :ref:`$r <$n>`\\ "; + my $s = $enum_symbols{$r}; $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; @@ -268,9 +286,7 @@ foreach my $r (keys %enum_symbols) { } foreach my $r (keys %enums) { - my $n = $enums{$r}; - - my $s = "\\ :ref:`enum $r <$n>`\\ "; + my $s = $enums{$r}; $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; @@ -280,9 +296,7 @@ foreach my $r (keys %enums) { } foreach my $r (keys %structs) { - my $n = $structs{$r}; - - my $s = "\\ :ref:`struct $r <$n>`\\ "; + my $s = $structs{$r}; $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; @@ -292,18 +306,15 @@ foreach my $r (keys %structs) { } foreach my $r (keys %typedefs) { - my $n = $typedefs{$r}; - - my $s = "\\ :ref:`$r <$n>`\\ "; + my $s = $typedefs{$r}; $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; print "$r -> $s\n" if ($debug); - $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g; } -$data =~ s/\\ \n/\n/g; +$data =~ s/\\ ([\n\s])/\1/g; # # Generate output file diff --git a/Documentation/sphinx/rstFlatTable.py b/Documentation/sphinx/rstFlatTable.py index 26db852e3c74..55f275793028 100644..100755 --- 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): # ============================================================================== |
