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]