def create_body_overloads(self) -> StringList:
"""
Create the overloaded implementations for insertion into to the body of the documenter's output.
"""
output = StringList()
formatted_overloads = []
output.blankline()
# output.append(":Overloaded Implementations:")
output.append(":Overloads:")
output.blankline()
# Size varies depending on docutils config
output.indent_type = ' '
output.indent_size = self.env.app.config.docutils_tab_width # type: ignore
if self.analyzer and '.'.join(self.objpath) in self.analyzer.overloads:
for overload in self.analyzer.overloads.get('.'.join(self.objpath)): # type: ignore
overload = self.process_overload_signature(overload)
buf = [format_annotation(self.object), r"\("]
for name, param in overload.parameters.items():
buf.append(f"**{name}**")
if param.annotation is not Parameter.empty:
buf.append(r"\: ")
buf.append(format_annotation(param.annotation))
if param.default is not Parameter.empty:
buf.append(" = ")
buf.append(param.default)
buf.append(r"\, ")
if buf[-2][-1] != '`':
buf[-1] = r" )"
else:
buf[-1] = r")"
if overload.return_annotation is not Parameter.empty:
buf.append(" -> ")
buf.append(format_annotation(overload.return_annotation))
formatted_overloads.append(''.join(buf))
if len(formatted_overloads) == 1:
output.append(formatted_overloads[0])
else:
for line in formatted_overloads:
output.append(f"* {line}")
output.blankline(ensure_single=True)
return output
return StringList()
def format_signature(obj: Union[type, FunctionType]) -> StringList:
"""
Format the signature of the given object, for insertion into the highlight panel.
:param obj:
:return: A list of reStructuredText lines.
"""
with monkeypatcher():
obj.__annotations__ = get_type_hints(obj)
signature: inspect.Signature = inspect.signature(obj)
buf = StringList(".. parsed-literal::")
buf.blankline()
buf.indent_type = " "
buf.indent_size = 1
if signature.return_annotation is not inspect.Signature.empty and not isinstance(
obj, type):
return_annotation = f") -> {format_annotation(signature.return_annotation)}"
else:
return_annotation = f")"
total_length = len(obj.__name__) + len(return_annotation)
arguments_buf: DelimitedList[str] = DelimitedList()
param: inspect.Parameter
for param in signature.parameters.values():
arguments_buf.append(f"{format_parameter(param)}")
total_length += len(arguments_buf[-1])
if total_length <= 60:
signature_buf = StringList(''.join(
[f"{obj.__name__}(", f"{arguments_buf:, }", return_annotation]))
else:
signature_buf = StringList([f"{obj.__name__}("])
signature_buf.indent_type = " "
with signature_buf.with_indent_size(1):
signature_buf.extend(
[f"{arguments_buf:,\n}" + ',', return_annotation])
buf.extend(signature_buf)
return buf
def test_indent_size(self):
sl = StringList(['', '', "hello", "world", '', '', '', "1234"])
assert sl.indent_size == 0
sl.indent_size = 7
assert sl.indent_size == 7
sl.set_indent_size()
assert sl.indent_size == 0
sl.set_indent_size(2)
assert sl.indent_size == 2
sl.indent_size += 1
assert sl.indent_size == 3
sl.indent_size -= 2
assert sl.indent_size == 1
def run_html(self) -> List[nodes.Node]:
"""
Generate output for ``HTML`` builders.
"""
# colours = itertools.cycle(self.delimited_get("colours", "#6ab0de"))
colours = itertools.cycle(
get_random_sample(self.delimited_get("colours", "blue")))
classes = list(
self.delimited_get(
"class",
"col-xl-6 col-lg-6 col-md-12 col-sm-12 col-xs-12 p-2"))
content = StringList()
content.append(".. panels::")
content.indent_type = " "
content.indent_size = 1
content.append(":container: container-xl pb-4 sphinx-highlights")
content.blankline()
for obj_name in get_random_sample(sorted(set(self.content))):
if self.options.get("module", '') and obj_name.startswith('.'):
obj_name = obj_name.replace('.', f"{self.options['module']}.",
1)
name_parts = obj_name.split('.')
module = import_module('.'.join(name_parts[:-1]))
obj = getattr(module, name_parts[-1])
colour_class = f"highlight-{next(colours)}"
content.append(
f":column: {DelimitedList((*classes, colour_class)): }")
if isinstance(obj, FunctionType):
content.append(
f":func:`{'.'.join(name_parts[1:])}() <.{obj_name}>`")
elif isinstance(obj, type):
content.append(
f":class:`{'.'.join(name_parts[1:])} <.{obj_name}>`")
else:
content.append(
f":py:obj:`{'.'.join(name_parts[1:])} <.{obj_name}>`")
content.append('^' * len(content[-1]))
content.blankline()
# content.append(f".. function:: {name_parts[-1]} {stringify_signature(inspect.signature(obj))}")
content.append(format_signature(obj))
content.blankline()
content.append(
inspect.cleandoc(obj.__doc__ or '').split("\n\n")[0])
content.blankline()
content.append(f"See more in :mod:`{module.__name__}`.")
content.append("---")
content.pop(-1)
targetid = f'sphinx-highlights-{self.env.new_serialno("sphinx-highlights"):d}'
targetnode = nodes.target('', '', ids=[targetid])
view = ViewList(content)
body_node = nodes.paragraph(rawsource=str(content))
self.state.nested_parse(view, self.content_offset,
body_node) # type: ignore
sphinx_highlights_purger.add_node(self.env, body_node, targetnode,
self.lineno)
return [targetnode, body_node]
