zuul
/
zuul-sphinx
Code Issues Proposed changes

Workaround circular import warning 

As detailed in the bug mentioned inline, if some of the lines the Zuul
directives are inserting also include another file, we will get
invalid circular reference warnings.

To work around this, clear the import list after inserting the lines
to to document.

Change-Id: I0bb465c37014d50802b8faa06b07cb461f0c683f
This commit is contained in:
Ian Wienand 2022-10-21 14:37:22 +11:00
parent 2272117b40
commit 504d2a42e6
No known key found for this signature in database
1 changed files with 21 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
zuul_sphinx/zuul.py
View File

@ -227,6 +227,21 @@ class ZuulDirective(Directive):
lines.append(' ' + l)
return lines
def insert_input(lines, filename):
self.state_machine.insert_input(lines, filename)
# NOTE(ianw) 2022-10-21 : The lines we just inserted may have
# inserted a file. If we try to insert that file again, we
# get a warning from docutils that there is a circular
# reference even though there isn't. This may be a bug, see
# https://sourceforge.net/p/docutils/bugs/459/
#
# This is not an API afict. Hence wrap this and only emit a
# debug if it fails incase upstream changes something.
try:
self.state.document.include_log = []
except Exception:
logger.debug("Unable to reset include_log")
class ZuulObjectDescription(ZuulDirective, ObjectDescription):
object_names = {
@ -582,7 +597,7 @@ class ZuulAutoJobDirective(ZuulDirective):
def run(self):
name = self.content[0]
lines = self.generate_zuul_job_content(name)
self.state_machine.insert_input(lines, self.zuul_layout_path)
self.insert_input(lines, self.zuul_layout_path)
return []
@ -599,7 +614,7 @@ class ZuulAutoJobsDirective(ZuulDirective):
lines = self.generate_zuul_job_content(name)
location = 'Job "%s" included in %s' % \
(name, env.doc2path(env.docname))
self.state_machine.insert_input(lines, location)
self.insert_input(lines, location)
names.add(name)
return []
@ -607,7 +622,7 @@ class ZuulAutoProjectTemplateDirective(ZuulDirective):
def run(self):
name = self.content[0]
lines = self.generate_zuul_project_template_content(name)
self.state_machine.insert_input(lines, self.zuul_layout_path)
self.insert_input(lines, self.zuul_layout_path)
return []
@ -624,7 +639,7 @@ class ZuulAutoProjectTemplatesDirective(ZuulDirective):
lines = self.generate_zuul_project_template_content(name)
location = 'Template "%s" included in %s' % \
(name, env.doc2path(env.docname))
self.state_machine.insert_input(lines, location)
self.insert_input(lines, location)
names.add(name)
return []
@ -633,7 +648,7 @@ class ZuulAutoRoleDirective(ZuulDirective):
def run(self):
name = self.content[0]
lines = self.generate_zuul_role_content(name)
self.state_machine.insert_input(lines, self.zuul_role_paths[name])
self.insert_input(lines, self.zuul_role_paths[name])
return []
@ -644,7 +659,7 @@ class ZuulAutoRolesDirective(ZuulDirective):
role_names = reversed(sorted(self.zuul_role_paths.keys()))
for name in role_names:
lines = self.generate_zuul_role_content(name)
self.state_machine.insert_input(lines, self.zuul_role_paths[name])
self.insert_input(lines, self.zuul_role_paths[name])
return []