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

tristanlatr · 2024-10-25T16:46:19Z

This change fixes #801 as well as introduce a rather a lot of refactoring and new ParsedDocstring features.

Parameters html are divided into .sig-param or .sig-symbol spans.
When the function is long enough (88 chars excluding the def and ending colon, this is hard coded) an extra CSS class .long-signature is added to the parent function-signature.
The first parameter 'cls' or 'self' of (class) methods is marked with the 'undocumented' CSS class, this way it's clearly not part of the API.
Add some CSS to expand the signature of long functions when they have the focus.
Refactor CSS rules for parameters tables to be more simpler and predictable with percentage values for smaller screens.
Remove ValueFormatter classes since they were only a hack to show HTML tags inside Signature.__str__(), which we don't need anymore because we're computing the representation ourselve.
Remove ParsedStanOnly class because we know have better alternatives.
Introduce ParsedDocstring.to_text() -> str.
ParsedDocstring.with_tag(Tag) -> ParsedDocstring.
ParsedDocstring.combine(list[ParsedDocsrting]) -> ParsedDocstring.
When a function has invalid parameters its rendered as (…) instead of confusing () - like it was a zero argument callable.

Examples:

Not wrapped because overloaded function never get wrapped.

Wrapped because the function length is over 88 chars

The way to get the old behaviour back is to use the following custom css:

.sig-param, .sig-symbol {
    display: initial !important;
    margin-left: 0 !important;
    padding-left: 0 !important;
}

…ill help to construct one parsed docstring from several parts.

We mimic the Signature.__str__ method for the implementation but instead of returning a str we return a ParsedDocstring, which is far more convenient. This change fixes #801: - Parameters html are divided into .sig-param spans. - When the function is long enought an extra CSS class .expand-signature is added to the parent function-signature. - The first parameter 'cls' or 'self' of (class) methods is marked with the 'undocumented' CSS class, this way it's clearly not part of the API. - Add some CSS to expand the signature of long functions when they have the focus only.

…miza a little the _colorize_signature() function.

codecov · 2024-10-25T20:55:30Z

Codecov Report

Attention: Patch coverage is 96.25000% with 9 lines in your changes missing coverage. Please review.

Project coverage is 92.85%. Comparing base (02063d3) to head (56168f8).

Files with missing lines	Patch %	Lines
pydoctor/epydoc/markup/__init__.py	90.90%	6 Missing ⚠️
pydoctor/epydoc2stan.py	97.11%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #831      +/-   ##
==========================================
+ Coverage   92.79%   92.85%   +0.05%     
==========================================
  Files          47       47              
  Lines        8468     8588     +120     
  Branches     1550     1578      +28     
==========================================
+ Hits         7858     7974     +116     
- Misses        350      353       +3     
- Partials      260      261       +1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

… docstrings they only update the local to_stan() method dynamically.

…w parsed docstrings they only update the local to_stan() method dynamically." This reverts commit eca5ced.

…class. Introduce ParsedDocstring.to_text().

…s when overloads are overwhelming... This probably requires some more tweaks but it's still better than showing everything at once.

…t try to do such things either...

Fix some cyclic imports issue as a drive-by change: model.Documentable was uncessarly runtime imported inside restructuredtext and epydoc parsers.

README.rst

github-actions · 2024-12-13T20:48:39Z

According to pydoctor_primer, this change doesn't affect pydoctor warnings on a corpus of open source code. ✅

tristanlatr · 2024-12-15T17:56:02Z

pydoctor/epydoc2stan.py

@@ -997,7 +976,7 @@ def colorized_pyval_fallback(_: List[ParseError], doc:ParsedDocstring, __:model.
    """


Looks like this docstring is wrong

tristanlatr · 2025-01-10T17:04:34Z

pydoctor/epydoc2stan.py

+
+    if param.default is not _empty:
+        if param.annotation is not _empty:
+            # TODO: should we keep these two different manners ?


github-actions · 2025-01-14T13:32:05Z

According to pydoctor_primer, this change doesn't affect pydoctor warnings on a corpus of open source code. ✅

tristanlatr · 2025-01-18T14:53:03Z

This would need a review. I don’t know how to get this done other than asking you directly @glyph. It’s been a while that I’m waiting…

glyph · 2025-01-22T19:50:29Z

@tristanlatr sorry for the delay, it'll probably be a few more days (pydoctor reviews are extra hard, in addition to having limited time!) but these are on my to-do list.

tristanlatr · 2025-01-23T15:53:37Z

Thanks for your message @glyph, please take your time. It's good to see that it's in the todo list of someone somewhere already. I'm sorry if this PR comes with rather a few refactors... I could try to split it up... Tell me if that would help you. Thanks

glyph

I do wish I understood this code a bit better, but the type checker is doing some good heavy lifting assuaging my concerns :). The new style looks great, and I look forward to deploying this. Thanks!

glyph · 2025-02-04T01:18:20Z

docs/google_demo/__init__.py

@@ -297,4 +297,4 @@ class ExamplePEP526Class:
    """

    attr1: str
-    attr2: int
+    attr2: int


Is this change intentional?

No I don’t think so…

glyph · 2025-02-04T01:19:55Z

pydoctor/epydoc/markup/__init__.py

+
+    @property
+    def has_body(self) -> bool: 
+        return any(e.has_body for e in self._elements)


Huh, why the coverage gap on these properties?

Because has_body is only used at one place: in the properties documentation processing. And properties don’t have this kind of parsed docstring. But I can always add a small test to cover that branch.

glyph · 2025-02-04T01:21:05Z

pydoctor/epydoc/markup/_pyval_repr.py

+def colorize_pyval(pyval: Any, linelen:Optional[int], maxlines:int, 
+                   linebreakok:bool=True, refmap:Optional[Dict[str, str]]=None, 
+                   is_annotation: bool = False) -> ColorizedPyvalRepr:


should we be adopting Black so that this sort of style change doesn't require discretion? :)

Yes we should… #851 and PR #859. But I don’t have the courage to deal with the merge conflicts yet

glyph · 2025-02-04T01:21:28Z

pydoctor/epydoc/markup/_types.py

        """
+        #TODO: Fix this soon


Link to an issue?

Yes. #873.
And even a PR that is a work in progress #874

glyph · 2025-02-04T01:24:05Z

pydoctor/templatewriter/search.py

-                # some ParsedDocstring subclass raises NotImplementedError on calling to_node()
-                # Like ParsedPlaintextDocstring.
-                doc = source.docstring
+            doc = ob.parsed_docstring.to_text()


lovely to see an ugly too-broad try like this go away :)

pydoctor/test/epydoc/test_pyval_repr.py

Co-authored-by: Glyph <[email protected]>

github-actions · 2025-02-04T13:49:29Z

According to pydoctor_primer, this change doesn't affect pydoctor warnings on a corpus of open source code. ✅

tristanlatr

Thanks a lot for your review @glyph. I’ll adjust a few things as per your comment and merge that. I’de just like to have merged #872 before so the parameter style related changes can be removed from this PR

tristanlatr · 2025-01-24T03:56:55Z

pydoctor/themes/base/apidocs.css

@@ -253,8 +253,15 @@ ul ul ul ul ul ul ul {

 /* Argument name + type column table  */
 .fieldTable tr td.fieldArgContainer {


Suggested change

.fieldTable tr td.fieldArgContainer {

.fieldTable tr td.fieldArgContainer {

width: 325px;

tristanlatr · 2025-01-24T03:57:14Z

pydoctor/themes/base/apidocs.css

+    /* It not seems to work with percentage values
+    so I used px values, these are just indications for the
+    CSS auto layout table algo not to create tables 
+    with rather unbalanced columns width. */
+    max-width: 400px;
+}
+.fieldTable tr td.fieldArgDesc {
+    max-width: 600px;


Suggested change

/* It not seems to work with percentage values

so I used px values, these are just indications for the

CSS auto layout table algo not to create tables

with rather unbalanced columns width. */

max-width: 400px;

}

.fieldTable tr td.fieldArgDesc {

max-width: 600px;

tristanlatr · 2025-01-24T03:59:06Z

pydoctor/themes/base/apidocs.css

+    .fieldTable{
+        table-layout: fixed;
+    }
+    /* Argument name + type column table  */
+    .fieldTable tr td.fieldArgContainer {
+        width: 34%;
+    }


Suggested change

.fieldTable{

table-layout: fixed;

}

/* Argument name + type column table */

.fieldTable tr td.fieldArgContainer {

width: 34%;

}

tristanlatr · 2025-01-24T04:00:37Z

pydoctor/themes/readthedocs/readthedocstheme.css

 #childList a:target ~ .functionBody{
-    background-color: transparent;
-    box-shadow: none;
+    box-shadow: 7px 1px 0px 3px rgb(253 255 223), -36px 1px 0px 3px rgb(253 255 223);


Suggested change

box-shadow: 7px 1px 0px 3px rgb(253 255 223), -36px 1px 0px 3px rgb(253 255 223);

background-color: transparent;

box-shadow: none;

tristanlatr · 2025-01-24T04:01:13Z

pydoctor/themes/base/apidocs.css

@@ -320,24 +333,13 @@ ul ul ul ul ul ul ul {
    #splitTables > table tr td:nth-child(2) {
        width: 160px;
    }


Suggested change

}

}

/* Argument name + type column table */

.fieldTable tr td.fieldArgContainer {

width: 170px;

}

.fieldTable {

table-layout: fixed;

}

tristanlatr · 2025-02-04T04:39:50Z

pydoctor/epydoc/markup/__init__.py

@@ -328,6 +420,20 @@ def switch_context(self, ob:Optional['Documentable']) -> ContextManager[None]:
        in this case error will NOT be reported at all.
        """

+class NotFoundLinker(DocstringLinker):


The NotFoundLinker is already present in linker.py no need to have it here

tristanlatr · 2025-02-04T13:40:44Z

docs/google_demo/__init__.py

@@ -297,4 +297,4 @@ class ExamplePEP526Class:
    """

    attr1: str
-    attr2: int
+    attr2: int


No I don’t think so…

tristanlatr · 2025-02-04T13:44:47Z

pydoctor/epydoc/markup/_types.py

        """
+        #TODO: Fix this soon


Yes. #873.
And even a PR that is a work in progress #874

tristanlatr · 2025-02-04T13:47:20Z

pydoctor/epydoc/markup/_pyval_repr.py

+def colorize_pyval(pyval: Any, linelen:Optional[int], maxlines:int, 
+                   linebreakok:bool=True, refmap:Optional[Dict[str, str]]=None, 
+                   is_annotation: bool = False) -> ColorizedPyvalRepr:


Yes we should… #851 and PR #859. But I don’t have the courage to deal with the merge conflicts yet

tristanlatr · 2025-02-04T13:49:33Z

pydoctor/epydoc/markup/__init__.py

+
+    @property
+    def has_body(self) -> bool: 
+        return any(e.has_body for e in self._elements)


Because has_body is only used at one place: in the properties documentation processing. And properties don’t have this kind of parsed docstring. But I can always add a small test to cover that branch.

tristanlatr added 2 commits October 25, 2024 12:30

Introduce ParsedDocstring.with_linker()/.with_tag()/.combine(). The w…

dea121c

…ill help to construct one parsed docstring from several parts.