def resolve_xref(self, env, fromdocname, builder, typ, target, node,
contnode):
try:
info = self.data[str(typ)][target]
except KeyError:
text = contnode.rawsource
role = self.roles.get(typ)
if role is None:
return None
reporter = LoggingReporter(env.doc2path(fromdocname),
report_level=Reporter.WARNING_LEVEL,
halt_level=Reporter.SEVERE_LEVEL)
doctree = DummyDocument(reporter)
resnode = role.result_nodes(doctree, env, node, None)[0][0]
if isinstance(resnode, addnodes.pending_xref):
text = node[0][0]
reporter = doctree.reporter
reporter.warning('Cannot resolve reference to %r' % text,
line=node.line)
return None
return resnode
else:
anchor = http_resource_anchor(typ, target)
title = typ.upper() + ' ' + target
return make_refnode(builder, fromdocname, info[0], anchor,
contnode, title)
def create_directive(self):
"""
Helper function to create a a "directive" suitable
for instantiating the TraitDocumenter with, along with resources
to support that directive, and clean up the resources afterwards.
Returns
-------
contextmanager
A context manager that returns a DocumenterBridge instance.
"""
with self.tmpdir() as tmpdir:
# Ensure configuration file exists.
conf_file = os.path.join(tmpdir, "conf.py")
with open(conf_file, "w", encoding="utf-8") as f:
f.write(CONF_PY)
app = SphinxTestApp(srcdir=path(tmpdir))
app.builder.env.app = app
app.builder.env.temp_data["docname"] = "dummy"
kwds = {}
state = mock.Mock()
state.document.settings.tab_width = 8
kwds["state"] = state
yield DocumenterBridge(
app.env, LoggingReporter(''), Options(), 1, **kwds)
def create_directive(self):
"""
Helper function to create a a "directive" suitable
for instantiating the TraitDocumenter with, along with resources
to support that directive, and clean up the resources afterwards.
Returns
-------
contextmanager
A context manager that returns a DocumenterBridge instance.
"""
with self.tmpdir() as tmpdir:
# Ensure configuration file exists.
conf_file = os.path.join(tmpdir, "conf.py")
with open(conf_file, "w", encoding="utf-8") as f:
f.write(CONF_PY)
app = SphinxTestApp(srcdir=path(tmpdir))
app.builder.env.app = app
app.builder.env.temp_data["docname"] = "dummy"
# Backwards compatibility hack: for now, we need to be compatible
# with both Sphinx < 2.1 (whose DocumenterBridge doesn't take
# a state argument) and Sphinx >= 2.3 (which warns if the state
# isn't passed). Eventually we should be able to drop support
# for Sphinx < 2.1.
kwds = {}
if sphinx.version_info >= (2, 1):
state = mock.Mock()
state.document.settings.tab_width = 8
kwds["state"] = state
yield DocumenterBridge(
app.env, LoggingReporter(''), Options(), 1, **kwds)
def get_doctree(self, docname: str) -> nodes.document:
"""Read the doctree for a file from the pickle and return it."""
filename = path.join(self.doctreedir, docname + '.doctree')
with open(filename, 'rb') as f:
doctree = pickle.load(f)
doctree.settings.env = self
doctree.reporter = LoggingReporter(self.doc2path(docname))
return doctree
def new_document(self):
# type: () -> nodes.document
document = standalone.Reader.new_document(self)
reporter = document.reporter
document.reporter = LoggingReporter(reporter.source, reporter.report_level,
reporter.halt_level, reporter.debug_flag,
reporter.error_handler)
return document
def do_autodoc(app, objtype, name, options={}):
doccls = app.registry.documenters[objtype]
docoptions = process_documenter_options(doccls, app.config, options)
bridge = DocumenterBridge(app.env, LoggingReporter(''), docoptions, 1)
documenter = doccls(bridge, name)
documenter.generate()
return bridge.result
def get_doctree(self, docname):
# type: (unicode) -> nodes.Node
"""Read the doctree for a file from the pickle and return it."""
doctree_filename = self.doc2path(docname, self.doctreedir, '.doctree')
with open(doctree_filename, 'rb') as f:
doctree = pickle.load(f)
doctree.settings.env = self
doctree.reporter = LoggingReporter(self.doc2path(docname))
return doctree
def new_document(self):
# type: () -> nodes.document
"""Creates a new document object which having a special reporter object good
for logging.
"""
document = standalone.Reader.new_document(self)
reporter = document.reporter
document.reporter = LoggingReporter.from_reporter(reporter)
document.reporter.set_source(self.source)
return document
def do_autodoc(app, objtype, name, options=None):
if options is None:
options = {}
app.env.temp_data.setdefault("docname", "index") # set dummy docname
doccls = app.registry.documenters[objtype]
docoptions = process_documenter_options(doccls, app.config, options)
state = Mock()
state.document.settings.tab_width = 8
bridge = DocumenterBridge(app.env, LoggingReporter(""), docoptions, 1,
state)
documenter = doccls(bridge, name)
documenter.generate()
return bridge.result
def new_document(self) -> nodes.document:
"""Creates a new document object which having a special reporter object good
for logging.
"""
document = super().new_document()
# substitute transformer
document.transformer = SphinxTransformer(document)
document.transformer.set_environment(self.settings.env)
# substitute reporter
reporter = document.reporter
document.reporter = LoggingReporter.from_reporter(reporter)
return document
def new_document(self):
# type: () -> nodes.document
"""Creates a new document object which having a special reporter object good
for logging.
"""
document = standalone.Reader.new_document(self)
# substitute transformer
document.transformer = SphinxTransformer(document)
document.transformer.set_environment(self.env)
# substitute reporter
reporter = document.reporter
document.reporter = LoggingReporter.from_reporter(reporter)
return document
def new_document(self):
# type: () -> nodes.document
"""Creates a new document object which having a special reporter object good
for logging.
"""
document = standalone.Reader.new_document(self)
# substitute transformer
document.transformer = SphinxTransformer(document)
document.transformer.set_environment(self.env)
# substitute reporter
reporter = document.reporter
document.reporter = LoggingReporter.from_reporter(reporter)
return document
def new_document(self) -> nodes.document:
"""
Creates a new document object which has a special reporter object good
for logging.
"""
document = super().new_document()
document.__class__ = addnodes.document # replace the class with patched version
# substitute transformer
document.transformer = SphinxTransformer(document)
document.transformer.set_environment(self.settings.env)
# substitute reporter
reporter = document.reporter
document.reporter = LoggingReporter.from_reporter(reporter)
return document
def create_directive(self):
"""
Helper function to create a a "directive" suitable
for instantiating the TraitDocumenter with, along with resources
to support that directive, and clean up the resources afterwards.
Returns
-------
contextmanager
A context manager that returns a DocumenterBridge instance.
"""
with self.tmpdir() as tmpdir:
# The configuration file must exist, but it's okay if it's empty.
conf_file = os.path.join(tmpdir, "conf.py")
with io.open(conf_file, "w", encoding="utf-8"):
pass
app = SphinxTestApp(srcdir=path(tmpdir))
app.builder.env.app = app
app.builder.env.temp_data["docname"] = "dummy"
yield DocumenterBridge(app.env, LoggingReporter(''), Options(), 1)
def apply(self):
config = self.document.settings.env.config
settings, source = self.document.settings, self.document['source']
codes = resource_filename(__name__, 'codes.json')
replacements = json.load(open(codes, encoding='utf-8'))
to_handle = (set(replacements.keys()) -
set(self.document.substitution_defs))
for ref in self.document.traverse(nodes.substitution_reference):
refname = ref['refname']
if refname in to_handle:
text = replacements[refname]
doc = new_document(source, settings)
doc.reporter = LoggingReporter.from_reporter(doc.reporter)
self.parser.parse(text, doc)
substitution = doc.next_node()
# Remove encapsulating paragraph
if isinstance(substitution, nodes.paragraph):
substitution = substitution.next_node()
ref.replace_self(substitution)
def apply(self):
# type: () -> None
config = self.document.settings.env.config
settings, source = self.document.settings, self.document['source']
global_substitutions = config['global_substitutions']
to_handle = (set(global_substitutions.keys())
- set(self.document.substitution_defs))
for ref in self.document.traverse(nodes.substitution_reference):
refname = ref['refname']
if refname in to_handle:
text = global_substitutions[refname]
doc = new_document(source, settings)
doc.reporter = LoggingReporter.from_reporter(doc.reporter)
self.parser.parse(text, doc)
substitution = doc.next_node()
# Remove encapsulating paragraph
if isinstance(substitution, nodes.paragraph):
substitution = substitution.next_node()
ref.replace_self(substitution)
