def get_resolver(self,
modules: List[docspec.Module]) -> Optional[Resolver]:
"""
Returns a simple #Resolver implementation. Finds cross-references in the same file.
"""
reverse_map = docspec.ReverseMap(modules)
def _resolve_reference(obj: docspec.ApiObject,
ref: List[str]) -> Optional[docspec.ApiObject]:
for part_name in ref:
obj = docspec.get_member(obj, part_name)
if not obj:
return None
return obj
def _find_reference(obj: docspec.ApiObject,
ref: List[str]) -> Optional[docspec.ApiObject]:
while obj:
resolved = _resolve_reference(obj, ref)
if resolved:
return resolved
obj = reverse_map.get_parent(obj)
return None
@Resolver
def resolver(obj: docspec.ApiObject, ref: str) -> Optional[str]:
target = _find_reference(obj, ref.split('.'))
if target:
return '#' + self._generate_object_id(target)
return None
return resolver
def filtered_modules(
self, modules: List[docspec.Module]) -> List[docspec.Module]:
"""
Creates a copy of the module graph where only the API objects selected
via #Page.contents are visible.
"""
modules = copy.deepcopy(modules)
reverse_map = docspec.ReverseMap(modules)
matched_contents = set()
def _match(obj: docspec.ApiObject) -> bool:
if getattr(obj, 'members', []):
return True
if self.contents:
path = '.'.join(x.name for x in reverse_map.path(obj))
for x in self.contents:
if fnmatch.fnmatch(path, x):
matched_contents.add(x)
return True
return False
docspec.filter_visit(modules, _match, order='post')
unmatched_contents = set(self.contents or ()) - matched_contents
if unmatched_contents:
logger.warning(
'Page(title=%r).contents has unmatched elements: %s. Did you spell it correctly? Does '
'a processor filter out this object?',
self.title,
', '.join(unmatched_contents),
)
return modules
def render_to_stream(self, modules: List[docspec.Module], stream: TextIO):
self._reverse_map = docspec.ReverseMap(modules)
if self.render_toc:
if self.render_toc_title:
stream.write('# {}\n\n'.format(self.render_toc_title))
for m in modules:
self._render_toc(stream, 0, m)
stream.write('\n')
for m in modules:
self._render_recursive(stream, 1, m)
def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]):
unresolved = {}
if resolver:
reverse = docspec.ReverseMap(modules)
docspec.visit(modules, lambda x: self._preprocess_refs(x, resolver, reverse, unresolved))
if unresolved:
summary = []
for uid, refs in unresolved.items():
summary.append(' {}: {}'.format(uid, ', '.join(refs)))
logger.warning(
'%s cross-reference(s) could not be resolved:\n%s',
sum(map(len, unresolved.values())),
'\n'.join(summary),
)
def process(self, modules: List[docspec.Module],
resolver: Optional[Resolver]):
unresolved = {}
if resolver:
reverse = docspec.ReverseMap(modules)
docspec.visit(
modules,
lambda x: self._preprocess_refs(x, resolver, reverse,
unresolved),
)
if unresolved:
summary = [
" {}: {}".format(uid, ", ".join(refs))
for uid, refs in unresolved.items()
]
logger.warning(
"%s cross-reference(s) could not be resolved:\n%s",
sum(map(len, unresolved.values())),
"\n".join(summary),
)