Wrap signatures onto several lines when function len is over a treshold and function has the focus

.github/workflows/system.yaml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        tox_target: [twisted-apidoc, cpython-summary, python-igraph-apidocs, cpython-apidocs, numpy-apidocs, git-buildpackage-apidocs, pytype-apidocs]
+        tox_target: [twisted-apidoc, cpython-summary, python-igraph-apidocs, cpython-apidocs, numpy-apidocs, git-buildpackage-apidocs, pytype-apidocs, temporalio-apidocs]
 
     steps:
     - uses: actions/checkout@v4

README.rst

@@ -74,6 +74,8 @@ in development
 ^^^^^^^^^^^^^^
 
 * Drop support for Python 3.8.
+* Signatures of function definitions are now wrapped onto several lines when the function has the focus. 
+* The first parameter of classmethods and methods (``cls`` or ``self``) is colored in gray so it's clear that these are not part of the API.
 
 pydoctor 24.11.1
 ^^^^^^^^^^^^^^^^

docs/google_demo/__init__.py

@@ -297,4 +297,4 @@ class ExamplePEP526Class:
     """
 
     attr1: str
-    attr2: int
+    attr2: int

docs/tests/test.py

@@ -197,7 +197,8 @@ def test_search(query:str, expected:List[str], order_is_important:bool=True) ->
                     'pydoctor.epydoc.markup.plaintext.ParsedPlaintextDocstring.to_stan',
                     'pydoctor.epydoc.markup._types.ParsedTypeDocstring.to_stan',
                     'pydoctor.epydoc.markup._pyval_repr.ColorizedPyvalRepr.to_stan',
-                    'pydoctor.epydoc2stan.ParsedStanOnly.to_stan',
+                    'pydoctor.epydoc.markup._ParsedDocstringTree.to_stan',
+                    'pydoctor.epydoc.markup._ParsedDocstringWithTag.to_stan',
                 ]
         test_search('to_stan*', to_stan_results, order_is_important=False)
         test_search('to_stan', to_stan_results, order_is_important=False)
@@ -208,7 +209,8 @@ def test_search(query:str, expected:List[str], order_is_important:bool=True) ->
                     'pydoctor.epydoc.markup._types.ParsedTypeDocstring.to_node',
                     'pydoctor.epydoc.markup.restructuredtext.ParsedRstDocstring.to_node',
                     'pydoctor.epydoc.markup.epytext.ParsedEpytextDocstring.to_node',
-                    'pydoctor.epydoc2stan.ParsedStanOnly.to_node',
+                    'pydoctor.epydoc.markup._ParsedDocstringTree.to_node',
+                    'pydoctor.epydoc.markup._ParsedDocstringWithTag.to_node',
                 ]
         test_search('to_node*', to_node_results, order_is_important=False)
         test_search('to_node', to_node_results, order_is_important=False)
@@ -250,8 +252,7 @@ def test_missing_subclasses():
     infos = ('pydoctor.epydoc.markup._types.ParsedTypeDocstring', 
         'pydoctor.epydoc.markup.epytext.ParsedEpytextDocstring', 
         'pydoctor.epydoc.markup.plaintext.ParsedPlaintextDocstring', 
-        'pydoctor.epydoc.markup.restructuredtext.ParsedRstDocstring', 
-        'pydoctor.epydoc2stan.ParsedStanOnly', )
+        'pydoctor.epydoc.markup.restructuredtext.ParsedRstDocstring', )
 
     with open(BASE_DIR / 'api' / 'pydoctor.epydoc.markup.ParsedDocstring.html', 'r', encoding='utf-8') as stream:
         page = stream.read()

pydoctor/astbuilder.py

@@ -13,12 +13,14 @@
     Type, TypeVar, Union, Set, cast
 )
 
-from pydoctor import epydoc2stan, model, node2stan, extensions, linker
-from pydoctor.epydoc.markup._pyval_repr import colorize_inline_pyval
+from pydoctor import epydoc2stan, model, extensions
 from pydoctor.astutils import (is_none_literal, is_typing_annotation, is_using_annotations, is_using_typing_final, node2dottedname, node2fullname, 
                                is__name__equals__main__, unstring_annotation, upgrade_annotation, iterassign, extract_docstring_linenum, infer_type, get_parents,
                                get_docstring_node, get_assign_docstring_node, unparse, NodeVisitor, Parentage, Str)
 
+class InvalidSignatureParamName(str):
+    def isidentifier(self) -> bool:
+        return True
 
 def parseFile(path: Path) -> ast.Module:
     """Parse the contents of a Python source file."""
@@ -1032,9 +1034,9 @@ def get_default(index: int) -> Optional[ast.expr]:
 
         parameters: List[Parameter] = []
         def add_arg(name: str, kind: Any, default: Optional[ast.expr]) -> None:
-            default_val = Parameter.empty if default is None else _ValueFormatter(default, ctx=func)
+            default_val = Parameter.empty if default is None else default
                                                                                # this cast() is safe since we're checking if annotations.get(name) is None first
-            annotation = Parameter.empty if annotations.get(name) is None else _AnnotationValueFormatter(cast(ast.expr, annotations[name]), ctx=func)
+            annotation = Parameter.empty if annotations.get(name) is None else cast(ast.expr, annotations[name])
             parameters.append(Parameter(name, kind, default=default_val, annotation=annotation))
 
         for index, arg in enumerate(posonlyargs):
@@ -1056,12 +1058,15 @@ def add_arg(name: str, kind: Any, default: Optional[ast.expr]) -> None:
             add_arg(kwarg.arg, Parameter.VAR_KEYWORD, None)
 
         return_type = annotations.get('return')
-        return_annotation = Parameter.empty if return_type is None or is_none_literal(return_type) else _AnnotationValueFormatter(return_type, ctx=func)
+        return_annotation = Parameter.empty if return_type is None or is_none_literal(return_type) else return_type
         try:
             signature = Signature(parameters, return_annotation=return_annotation)
         except ValueError as ex:
             func.report(f'{func.fullName()} has invalid parameters: {ex}')
-            signature = Signature()
+            # Craft an invalid signature that does not look like a function with zero arguments.
+            signature = Signature(
+                [Parameter(InvalidSignatureParamName('...'), 
+                           kind=Parameter.POSITIONAL_OR_KEYWORD)])
 
         func.annotations = annotations
 
@@ -1120,7 +1125,7 @@ def _annotations_from_function(
         @param func: The function definition's AST.
         @return: Mapping from argument name to annotation.
             The name C{return} is used for the return type.
-            Unannotated arguments are omitted.
+            Unannotated arguments are still included with a None value.
         """
         def _get_all_args() -> Iterator[ast.arg]:
             base_args = func.args
@@ -1149,47 +1154,7 @@ def _get_all_ast_annotations() -> Iterator[Tuple[str, Optional[ast.expr]]]:
                 value, self.builder.current), self.builder.current)
             for name, value in _get_all_ast_annotations()
             }
-
-class _ValueFormatter:
-    """
-    Class to encapsulate a python value and translate it to HTML when calling L{repr()} on the L{_ValueFormatter}.
-    Used for presenting default values of parameters.
-    """
-
-    def __init__(self, value: ast.expr, ctx: model.Documentable):
-        self._colorized = colorize_inline_pyval(value)
-        """
-        The colorized value as L{ParsedDocstring}.
-        """
-
-        self._linker = ctx.docstring_linker
-        """
-        Linker.
-        """
 
-    def __repr__(self) -> str:
-        """
-        Present the python value as HTML. 
-        Without the englobing <code> tags.
-        """
-        # Using node2stan.node2html instead of flatten(to_stan()). 
-        # This avoids calling flatten() twice, 
-        # but potential XML parser errors caused by XMLString needs to be handled later.
-        return ''.join(node2stan.node2html(self._colorized.to_node(), self._linker))
-
-class _AnnotationValueFormatter(_ValueFormatter):
-    """
-    Special L{_ValueFormatter} for function annotations.
-    """
-    def __init__(self, value: ast.expr, ctx: model.Function):
-        super().__init__(value, ctx)
-        self._linker = linker._AnnotationLinker(ctx)
-
-    def __repr__(self) -> str:
-        """
-        Present the annotation wrapped inside <code> tags.
-        """
-        return '<code>%s</code>' % super().__repr__()
 
 DocumentableT = TypeVar('DocumentableT', bound=model.Documentable)
 

pydoctor/epydoc/markup/__init__.py

@@ -33,7 +33,9 @@
 from __future__ import annotations
 __docformat__ = 'epytext en'
 
-from typing import Callable, ContextManager, List, Optional, Sequence, Iterator, TYPE_CHECKING
+import contextlib
+from itertools import chain
+from typing import Callable, ContextManager, Iterable, List, Optional, Sequence, Iterator, TYPE_CHECKING
 import abc
 import re
 from importlib import import_module
@@ -132,7 +134,7 @@
     markup parsers such as L{pydoctor.epydoc.markup.epytext.parse_docstring()}
     or L{pydoctor.epydoc.markup.restructuredtext.parse_docstring()}.
 
-    Subclasses must implement L{has_body()} and L{to_node()}.
+    Subclasses must at least implement L{has_body()} and L{to_node()}.
 
     A default implementation for L{to_stan()} method, relying on L{to_node()} is provided.
     But some subclasses override this behaviour.
@@ -146,11 +148,10 @@
         A list of L{Field}s, each of which encodes a single field.
         The field's bodies are encoded as C{ParsedDocstring}s.
         """
-
         self._stan: Optional[Tag] = None
-        self._summary: Optional['ParsedDocstring'] = None
 
-    @abc.abstractproperty
+    @property  
+    @abc.abstractmethod  
     def has_body(self) -> bool:
         """
         Does this docstring have a non-empty body?
@@ -171,7 +172,6 @@
         docstring_toc = new_document('toc')
         if contents:
             docstring_toc.extend(contents)
-            from pydoctor.epydoc.markup.restructuredtext import ParsedRstDocstring
             return ParsedRstDocstring(docstring_toc, ())
         else:
             return None
@@ -206,25 +206,115 @@
         """
         raise NotImplementedError()
 
+    def to_text(self) -> str:
+        """
+        Translate this docstring to a string.
+        The default implementation depends on L{to_node}.
+        """
+        doc = self.to_node()
+        return ''.join(node2stan.gettext(doc))
+
+    def with_tag(self, tag: Tag) -> ParsedDocstring:
+        """
+        Wraps the L{to_stan()} result inside the given tag. 
+
+        This is useful because some code strips the main tag to keep only it's content. 
+        With this trick, the main tag is preserved. It can also be used to add
+        a custom CSS class on top of an existing parsed docstring.
+        """
+        return _ParsedDocstringWithTag(self, tag)
+
+    @classmethod
+    def combine(cls, elements: Sequence[ParsedDocstring]) -> ParsedDocstring:
+        """
+        Combine the contents of several parsed docstrings into one. 
+        """
+        return _ParsedDocstringTree(elements)
+
     def get_summary(self) -> 'ParsedDocstring':
         """
         Returns the summary of this docstring.
-
-        @note: The summary is cached.
         """
-        # Avoid rare cyclic import error, see https://github.com/twisted/pydoctor/pull/538#discussion_r845668735
-        from pydoctor import epydoc2stan
-        if self._summary is not None:
-            return self._summary
         try: 
             _document = self.to_node()
             visitor = SummaryExtractor(_document)
             _document.walk(visitor)
         except Exception: 
-            self._summary = epydoc2stan.ParsedStanOnly(tags.span(class_='undocumented')("Broken summary"))
-        else:
-            self._summary = visitor.summary or epydoc2stan.ParsedStanOnly(tags.span(class_='undocumented')("No summary"))
-        return self._summary
+            return parsed_text_with_css('Broken summary', 'undocumented')
+
+        return visitor.summary or parsed_text_with_css('No summary', 'undocumented')
+
+
+class _ParsedDocstringTree(ParsedDocstring):
+    """
+    Several parsed docstrings into a single one.
+    """
+
+    def __init__(self, elements: Sequence[ParsedDocstring]):
+        super().__init__(tuple(chain.from_iterable(e.fields for e in elements)))
+        self._elements = elements
+        self._doc: nodes.document | None = None
+
+    @property
+    def has_body(self) -> bool: 
+        return any(e.has_body for e in self._elements)
+
+    @classmethod
+    def _generate_document(cls, elements: Iterable[ParsedDocstring]) -> nodes.document:
+        doc = new_document('composite')
+        for e in elements:
+            # TODO: Some parsed doctrings simply do not implement to_node().
+            # It should be really time to fix this...
+            subdoc = e.to_node()
+            # TODO: here all childrens might not have the same document property.
+            # this should not be a problem, but docutils is likely not meant to be used like that.
+            doc.children.extend(subdoc.children)
+        return doc
+
+    def to_node(self) -> nodes.document:
+        if not self._doc:
+            self._doc = self._generate_document(self._elements)
+        return self._doc
+
+    def to_stan(self, linker: DocstringLinker) -> Tag: 
+        stan = tags.transparent()
+        for e in self._elements:
+            stan(e.to_stan(linker).children)
+        return stan
+
+class _ParsedDocstringWithTag(ParsedDocstring):
+    """
+    Wraps a parsed docstring to wrap the result of the 
+    the to_stan() method inside a custom Tag.
+    """
+    def __init__(self, 
+                 other: ParsedDocstring, 
+                 tag: Tag):
+        super().__init__(other.fields)
+        self.wrapped = other
+        """
+        The wrapped parsed docstring.
+        """
+        self._tag = tag
+        self._stan: Tag | None = None
+
+    # We double wrap it with a transparent tag so the added tags survives ParsedDocstring.combine 
+    # wich combines the content of the main div of the stan, not the div itself.
+    def to_stan(self, linker: DocstringLinker) -> Tag:
+        # Since the stan is cached inside _stan attribute we can't simply use
+        # "lambda this, linker: tags.transparent(self._tag(this.to_stan(linker)))" as the new to_stan method. 
+        # this would not behave correctly because each time to_stan will be called, the content would be duplicated.
+        if (stan:=self._stan) is not None:
+            return stan
+        self._stan = stan = Tag('')(self._tag(self.wrapped.to_stan(linker)))
+        return stan
+
+    # Boring
+    def to_node(self) -> nodes.document:
+        return self.wrapped.to_node()
+    @property
+    def has_body(self) -> bool: 
+        return self.wrapped.has_body
 
 
 ##################################################
@@ -289,14 +379,16 @@
     target URL for crossreference links.
     """
 
-    def link_to(self, target: str, label: "Flattenable") -> Tag:
+    def link_to(self, target: str, label: "Flattenable", *, is_annotation: bool = False) -> Tag:
         """
         Format a link to a Python identifier.
         This will resolve the identifier like Python itself would.
 
         @param target: The name of the Python identifier that
             should be linked to.
         @param label: The label to show for the link.
+        @param is_annotation: Generated links will give precedence to the module
+            defined variables rather the nested definitions when there are name collisions.
         @return: The link, or just the label if the target was not found.
         """
 
@@ -328,6 +420,20 @@
         in this case error will NOT be reported at all.
         """
 
+class NotFoundLinker(DocstringLinker):
+    """A DocstringLinker implementation that cannot find any links."""
+
+    def link_to(self, target: str, label: "Flattenable", *, is_annotation: bool = False) -> Tag:
+        return tags.transparent(label)
+
+    def link_xref(self, target: str, label: "Flattenable", lineno: int) -> Tag:
+        return tags.code(label)
+
+    @contextlib.contextmanager
+    def switch_context(self, ob: Documentable | None) -> Iterator[None]:
+        yield
+
+
 ##################################################
 ## ParseError exceptions
 ##################################################
@@ -478,11 +584,13 @@
             set_node_attributes(nodes.paragraph('', ''), document=summary_doc, lineno=1, 
             children=summary_pieces)])
 
-        from pydoctor.epydoc.markup.restructuredtext import ParsedRstDocstring
         self.summary = ParsedRstDocstring(summary_doc, fields=[])
 
     def visit_field(self, node: nodes.Node) -> None:
         raise nodes.SkipNode()
 
     def unknown_visit(self, node: nodes.Node) -> None:
         '''Ignore all unknown nodes'''
+
+
+from pydoctor.epydoc.markup.restructuredtext import ParsedRstDocstring, parsed_text_with_css

pydoctor/epydoc/markup/_napoleon.py

@@ -9,6 +9,7 @@
 from pydoctor.napoleon.docstring import GoogleDocstring, NumpyDocstring
 
 
+
 class NapoelonDocstringParser:
     """
     Parse google-style or numpy-style docstrings.
@@ -61,7 +62,6 @@ def _parse_docstring(
         errors: list[ParseError],
         docstring_cls: type[GoogleDocstring],
     ) -> ParsedDocstring:
-
         docstring_obj = docstring_cls(
             docstring, 
             what=self.objclass,