github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-24 06:29:19 +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/hv-cpu-virt.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.
^(?P<filename>[-._/\w]+/hld/[-._/\w]+.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 import nodes, statemachine
from docutils.statemachine import ViewList from docutils.statemachine import ViewList
from docutils.parsers.rst import directives, Directive 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' __version__ = '1.0'
@ -47,7 +50,7 @@ class KernelDocDirective(Directive):
optional_arguments = 4 optional_arguments = 4
option_spec = { option_spec = {
'doc': directives.unchanged_required, 'doc': directives.unchanged_required,
'functions': directives.unchanged_required, 'functions': directives.unchanged,
'export': directives.unchanged, 'export': directives.unchanged,
'internal': directives.unchanged, 'internal': directives.unchanged,
} }
@ -75,8 +78,12 @@ class KernelDocDirective(Directive):
elif 'doc' in self.options: elif 'doc' in self.options:
cmd += ['-function', str(self.options.get('doc'))] cmd += ['-function', str(self.options.get('doc'))]
elif 'functions' in self.options: elif 'functions' in self.options:
for f in str(self.options.get('functions')).split(): functions = self.options.get('functions').split()
cmd += ['-function', f] if functions:
for f in functions:
cmd += ['-function', f]
else:
cmd += ['-no-doc-sections']
for pattern in export_file_patterns: for pattern in export_file_patterns:
for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
@ -86,7 +93,7 @@ class KernelDocDirective(Directive):
cmd += [filename] cmd += [filename]
try: 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) p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
out, err = p.communicate() out, err = p.communicate()
@ -96,7 +103,7 @@ class KernelDocDirective(Directive):
if p.returncode != 0: if p.returncode != 0:
sys.stderr.write(err) 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"))] return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
elif env.config.kerneldoc_verbosity > 0: elif env.config.kerneldoc_verbosity > 0:
sys.stderr.write(err) sys.stderr.write(err)
@ -118,17 +125,17 @@ class KernelDocDirective(Directive):
node = nodes.section() node = nodes.section()
buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter 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 self.state.memo.title_styles, self.state.memo.section_level = [], 0
try: 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: finally:
self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
return node.children return node.children
except Exception as e: # pylint: disable=W0703 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))) (" ".join(cmd), str(e)))
return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]