github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-23 22:18:17 +00:00
Code Issues Projects Releases Wiki Activity

doc: prepare for sphinx 2.0 upgrade

Browse Source 
Sphinx 2.0 reports some "expected errors" differently, so add the new
message patterns to our known-errors scanning.

Also, the kerneldoc tool has a problem with sphinx 2.0, but a fix was
available.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2019-05-22 09:30:46 -07:00 committed by David Kinder
parent 474496fc0e
commit cb6a3e8f08
2 changed files with 18 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/.known-issues/doc/dupdecl.conf
View File

@ -3,3 +3,5 @@
#
#^(?P<filename>[-._/\w]+/hld/hv-cpu-virt.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.
^(?P<filename>[-._/\w]+/hld/[-._/\w]+.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.
# Sphinx 2.0
^(?P<filename>[-._/\w]+/hld/[-._/\w]+.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration, .*

25
doc/extensions/kerneldoc.py
View File

@ -37,7 +37,10 @@ import glob
from docutils import nodes, statemachine
from docutils.statemachine import ViewList
from docutils.parsers.rst import directives, Directive
from sphinx.ext.autodoc import AutodocReporter
from sphinx.util.docutils import switch_source_input
from sphinx.util import logging
logger = logging.getLogger(__name__)
__version__ = '1.0'
@ -47,7 +50,7 @@ class KernelDocDirective(Directive):
optional_arguments = 4
option_spec = {
'doc': directives.unchanged_required,
'functions': directives.unchanged_required,
'functions': directives.unchanged,
'export': directives.unchanged,
'internal': directives.unchanged,
}
@ -75,8 +78,12 @@ class KernelDocDirective(Directive):
elif 'doc' in self.options:
cmd += ['-function', str(self.options.get('doc'))]
elif 'functions' in self.options:
for f in str(self.options.get('functions')).split():
cmd += ['-function', f]
functions = self.options.get('functions').split()
if functions:
for f in functions:
cmd += ['-function', f]
else:
cmd += ['-no-doc-sections']
for pattern in export_file_patterns:
for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
@ -86,7 +93,7 @@ class KernelDocDirective(Directive):
cmd += [filename]
try:
env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd)))
logger.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd)))
p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
out, err = p.communicate()
@ -96,7 +103,7 @@ class KernelDocDirective(Directive):
if p.returncode != 0:
sys.stderr.write(err)
env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))
logger.warning('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))
return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
elif env.config.kerneldoc_verbosity > 0:
sys.stderr.write(err)
@ -118,17 +125,17 @@ class KernelDocDirective(Directive):
node = nodes.section()
buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
self.state.memo.title_styles, self.state.memo.section_level = [], 0
try:
self.state.nested_parse(result, 0, node, match_titles=1)
with switch_source_input(self.state, result):
self.state.nested_parse(result, 0, node, match_titles=1)
finally:
self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
return node.children
except Exception as e: # pylint: disable=W0703
env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
logger.warning('kernel-doc \'%s\' processing failed with: %s' %
(" ".join(cmd), str(e)))
return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]