aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJani Nikula <jani.nikula@intel.com>2016-06-07 05:13:56 -0400
committerJani Nikula <jani.nikula@intel.com>2016-06-10 09:46:55 -0400
commit03d35d9ec4ae50afeafc3ab26d8207b7069f3cba (patch)
tree82f4957e9757b67e4db8b98edcc7db1ffb6e3000
parent057de5c4dd536bdf29275ec75910737087594860 (diff)
Documentation/sphinx: add support for specifying extra export files
Let the user specify file patterns where to look for the EXPORT_SYMBOLs in addition to the file with kernel-doc comments. This is directly based on the -export-file FILE option added to kernel-doc in "kernel-doc: add support for specifying extra files for EXPORT_SYMBOLs", but we extend that with globbing patterns in the Sphinx extension. The file patterns are added as options to the :export: and :internal: arguments of the kernel-doc directive. For example, to extract the documentation of exported functions from include/net/mac80211.h: .. kernel-doc:: include/net/mac80211.h :export: net/mac80211/*.c Without the file pattern, no exported functions would be found, as the EXPORT_SYMBOLs are placed in the various source files under net/mac80211. The matched files are also added as dependencies on the document in Sphinx, as they may affect the output. This is one of the reasons to do the globbing in the Sphinx extension instead of in scripts/kernel-doc. The file pattern remains optional, and is not needed if the kernel-doc comments and EXPORT_SYMBOLs are placed in the source file passed in as the main argument to the kernel-doc directive. This is the most common case across the kernel source tree. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
-rw-r--r--Documentation/sphinx/kernel-doc.py13
1 files changed, 11 insertions, 2 deletions
diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py
index d6a76f9a0ba5..dedb24e3bb7a 100644
--- a/Documentation/sphinx/kernel-doc.py
+++ b/Documentation/sphinx/kernel-doc.py
@@ -31,6 +31,7 @@ import os
31import subprocess 31import subprocess
32import sys 32import sys
33import re 33import re
34import glob
34 35
35from docutils import nodes, statemachine 36from docutils import nodes, statemachine
36from docutils.statemachine import ViewList 37from docutils.statemachine import ViewList
@@ -44,8 +45,8 @@ class KernelDocDirective(Directive):
44 option_spec = { 45 option_spec = {
45 'doc': directives.unchanged_required, 46 'doc': directives.unchanged_required,
46 'functions': directives.unchanged_required, 47 'functions': directives.unchanged_required,
47 'export': directives.flag, 48 'export': directives.unchanged,
48 'internal': directives.flag, 49 'internal': directives.unchanged,
49 } 50 }
50 has_content = False 51 has_content = False
51 52
@@ -54,6 +55,7 @@ class KernelDocDirective(Directive):
54 cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] 55 cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno']
55 56
56 filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] 57 filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
58 export_file_patterns = []
57 59
58 # Tell sphinx of the dependency 60 # Tell sphinx of the dependency
59 env.note_dependency(os.path.abspath(filename)) 61 env.note_dependency(os.path.abspath(filename))
@@ -63,14 +65,21 @@ class KernelDocDirective(Directive):
63 # FIXME: make this nicer and more robust against errors 65 # FIXME: make this nicer and more robust against errors
64 if 'export' in self.options: 66 if 'export' in self.options:
65 cmd += ['-export'] 67 cmd += ['-export']
68 export_file_patterns = str(self.options.get('export')).split()
66 elif 'internal' in self.options: 69 elif 'internal' in self.options:
67 cmd += ['-internal'] 70 cmd += ['-internal']
71 export_file_patterns = str(self.options.get('internal')).split()
68 elif 'doc' in self.options: 72 elif 'doc' in self.options:
69 cmd += ['-function', str(self.options.get('doc'))] 73 cmd += ['-function', str(self.options.get('doc'))]
70 elif 'functions' in self.options: 74 elif 'functions' in self.options:
71 for f in str(self.options.get('functions')).split(): 75 for f in str(self.options.get('functions')).split():
72 cmd += ['-function', f] 76 cmd += ['-function', f]
73 77
78 for pattern in export_file_patterns:
79 for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
80 env.note_dependency(os.path.abspath(f))
81 cmd += ['-export-file', f]
82
74 cmd += [filename] 83 cmd += [filename]
75 84
76 try: 85 try: