3 # Copyright © 2016 Intel Corporation
5 # Permission is hereby granted, free of charge, to any person obtaining a
6 # copy of this software and associated documentation files (the "Software"),
7 # to deal in the Software without restriction, including without limitation
8 # the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 # and/or sell copies of the Software, and to permit persons to whom the
10 # Software is furnished to do so, subject to the following conditions:
12 # The above copyright notice and this permission notice (including the next
13 # paragraph) shall be included in all copies or substantial portions of the
16 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19 # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
25 # Jani Nikula <jani.nikula@intel.com>
27 # Please make sure this works on both python2 and python3.
37 from docutils
import nodes
, statemachine
38 from docutils
.statemachine
import ViewList
39 from docutils
.parsers
.rst
import directives
, Directive
42 # AutodocReporter is only good up to Sphinx 1.7
46 Use_SSI
= sphinx
.__version
__[:3] >= '1.7'
48 from sphinx
.util
.docutils
import switch_source_input
50 from sphinx
.ext
.autodoc
import AutodocReporter
56 class KernelDocDirective(Directive
):
57 """Extract kernel-doc comments from the specified file"""
59 optional_arguments
= 4
61 'doc': directives
.unchanged_required
,
62 'functions': directives
.unchanged
,
63 'export': directives
.unchanged
,
64 'internal': directives
.unchanged
,
69 env
= self
.state
.document
.settings
.env
70 cmd
= env
.config
.kerneldoc_bin
+ ['-rst', '-enable-lineno']
72 filename
= env
.config
.kerneldoc_srctree
+ '/' + self
.arguments
[0]
73 export_file_patterns
= []
75 # Tell sphinx of the dependency
76 env
.note_dependency(os
.path
.abspath(filename
))
78 tab_width
= self
.options
.get('tab-width', self
.state
.document
.settings
.tab_width
)
80 # FIXME: make this nicer and more robust against errors
81 if 'export' in self
.options
:
83 export_file_patterns
= str(self
.options
.get('export')).split()
84 elif 'internal' in self
.options
:
86 export_file_patterns
= str(self
.options
.get('internal')).split()
87 elif 'doc' in self
.options
:
88 cmd
+= ['-function', str(self
.options
.get('doc'))]
89 elif 'functions' in self
.options
:
90 functions
= self
.options
.get('functions').split()
93 cmd
+= ['-function', f
]
95 cmd
+= ['-no-doc-sections']
97 for pattern
in export_file_patterns
:
98 for f
in glob
.glob(env
.config
.kerneldoc_srctree
+ '/' + pattern
):
99 env
.note_dependency(os
.path
.abspath(f
))
100 cmd
+= ['-export-file', f
]
102 cmd
+= ['-sphinx-version', sphinx
.__version
__]
106 kernellog
.verbose(env
.app
,
107 'calling kernel-doc \'%s\'' % (" ".join(cmd
)))
109 p
= subprocess
.Popen(cmd
, stdout
=subprocess
.PIPE
, stderr
=subprocess
.PIPE
)
110 out
, err
= p
.communicate()
112 out
, err
= codecs
.decode(out
, 'utf-8'), codecs
.decode(err
, 'utf-8')
114 if p
.returncode
!= 0:
115 sys
.stderr
.write(err
)
117 kernellog
.warn(env
.app
,
118 'kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd
), p
.returncode
))
119 return [nodes
.error(None, nodes
.paragraph(text
= "kernel-doc missing"))]
120 elif env
.config
.kerneldoc_verbosity
> 0:
121 sys
.stderr
.write(err
)
123 lines
= statemachine
.string2lines(out
, tab_width
, convert_whitespace
=True)
127 line_regex
= re
.compile("^#define LINENO ([0-9]+)$")
129 match
= line_regex
.search(line
)
131 # sphinx counts lines from 0
132 lineoffset
= int(match
.group(1)) - 1
133 # we must eat our comments since the upset the markup
135 result
.append(line
, filename
, lineoffset
)
138 node
= nodes
.section()
139 self
.do_parse(result
, node
)
143 except Exception as e
: # pylint: disable=W0703
144 kernellog
.warn(env
.app
, 'kernel-doc \'%s\' processing failed with: %s' %
145 (" ".join(cmd
), str(e
)))
146 return [nodes
.error(None, nodes
.paragraph(text
= "kernel-doc missing"))]
148 def do_parse(self
, result
, node
):
150 with
switch_source_input(self
.state
, result
):
151 self
.state
.nested_parse(result
, 0, node
, match_titles
=1)
153 save
= self
.state
.memo
.title_styles
, self
.state
.memo
.section_level
, self
.state
.memo
.reporter
154 self
.state
.memo
.reporter
= AutodocReporter(result
, self
.state
.memo
.reporter
)
155 self
.state
.memo
.title_styles
, self
.state
.memo
.section_level
= [], 0
157 self
.state
.nested_parse(result
, 0, node
, match_titles
=1)
159 self
.state
.memo
.title_styles
, self
.state
.memo
.section_level
, self
.state
.memo
.reporter
= save
163 app
.add_config_value('kerneldoc_bin', None, 'env')
164 app
.add_config_value('kerneldoc_srctree', None, 'env')
165 app
.add_config_value('kerneldoc_verbosity', 1, 'env')
167 app
.add_directive('kernel-doc', KernelDocDirective
)
170 version
= __version__
,
171 parallel_read_safe
= True,
172 parallel_write_safe
= True