Wrap signatures onto several lines when function len is over a treshold #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 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 the function len is below the threshold.

Wrapped

…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.34146% with 9 lines in your changes missing coverage. Please review.

Project coverage is 92.35%. Comparing base (cceabfa) to head (bd2de92).

Files with missing lines	Patch %	Lines
pydoctor/epydoc/markup/__init__.py	93.93%	4 Missing ⚠️
pydoctor/epydoc2stan.py	97.11%	2 Missing and 1 partial ⚠️
pydoctor/templatewriter/pages/__init__.py	91.30%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #831      +/-   ##
==========================================
+ Coverage   92.29%   92.35%   +0.05%     
==========================================
  Files          47       47              
  Lines        8514     8629     +115     
  Branches     1695     1725      +30     
==========================================
+ Hits         7858     7969     +111     
- Misses        385      387       +2     
- Partials      271      273       +2

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

🚨 Try these New Features:

Flaky Tests Detection - Detect and resolve failed and flaky tests
JS Bundle Analysis - Avoid shipping oversized bundles

… 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.

also remove the summary caching on the parsed docstring side, this is unnecessary because it's already cahed in the documentable.

…of a string. A some annotation.

… long annotations.

…nnotation is ambiguous (pydoctor is not a checker). Get rid of ParsedDocstring.with_linker() this API did not make sens and was rather an anti-pattern. Replace that with a new parameter of colorize_pyval(is_annotation: bool). obj_reference nodes can now be created with the attribute 'is_annotation' in which case they will be resolved a little bit differently.

…o 801-signature-spans

github-actions · 2024-11-21T17:05:58Z

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

tristanlatr · 2024-11-14T18:33:11Z

pydoctor/test/test_astbuilder.py

+    doc = get_parsed_signature(func)
+    assert doc
+    fromhtml = flatten_text(format_signature(func))
+    fromdocutils = ''.join(node2stan.gettext(doc.to_node()))


Suggested change

fromdocutils = ''.join(node2stan.gettext(doc.to_node()))

fromdocutils = doc.to_text()

tristanlatr · 2024-11-14T18:34:29Z

pydoctor/epydoc/markup/__init__.py

+            stan(e.to_stan(linker).children)
+        return stan
+
+class WrappedParsedDocstring(ParsedDocstring):


Suggested change

class WrappedParsedDocstring(ParsedDocstring):

class _WrappedParsedDocstring(ParsedDocstring):

tristanlatr · 2024-11-16T14:36:50Z

pydoctor/epydoc/markup/__init__.py

+            self._doc = self._generate_document(self._elements)
+        return self._doc
+
+    def to_stan(self, linker: DocstringLinker) -> Tag: 


Maybe cache the stan here as well.

tristanlatr · 2024-11-16T14:59:30Z

pydoctor/themes/base/apidocs.css

    word-break: break-word;
+    /* It not seems to work with percentage values
+    so I used px values, these are just indications for the
+    CSS auto layour table algo not to create tables 


Suggested change

CSS auto layour table algo not to create tables

CSS auto layout table algo not to create tables

tristanlatr · 2024-11-16T15:03:38Z

pydoctor/themes/base/apidocs.css

+#childList a:target ~ .functionHeader .function-signature.long-signature .sig-param, 
+#childList a:target ~ .functionHeader .function-signature.long-signature .sig-symbol {
+    display: block;
+    margin-left: 1.5em;
+    padding-left: 1.5em;
+    text-indent: -1.5em;
+}
+/* Except the 'self' or 'cls' params, which are rendered on the same line as the function def */
+#childList a:target ~ .functionHeader .function-signature.long-signature .sig-param:has(.undocumented) {
+    display: initial;
+    margin-left: 0;
+    padding-left: 0;
+}


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; }

tristanlatr · 2024-11-16T19:07:03Z

pydoctor/epydoc/markup/__init__.py

        """
        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 varaible rather the nested definitions when there are name colisions.


Suggested change

defined varaible rather the nested definitions when there are name colisions.

defined variables rather the nested definitions when there are name collisions.

tristanlatr · 2024-11-16T19:09:22Z

pydoctor/epydoc/markup/restructuredtext.py

+    set_node_attributes(document, children=[txt_node])
+    return ParsedRstDocstring(document, ())
+
+# not using cache here because we need new span tag for every call 


Suggested change

# not using cache here because we need new span tag for every call

tristanlatr · 2024-11-16T19:09:35Z

pydoctor/epydoc/markup/restructuredtext.py

+    return ParsedRstDocstring(document, ())
+
+# not using cache here because we need new span tag for every call 
+# othewise it messes-up everything.


Suggested change

# othewise it messes-up everything.

tristanlatr · 2024-11-16T19:13:00Z

pydoctor/epydoc2stan.py

+                              has_next: bool, 
+                              is_first: bool, ) -> ParsedDocstring:
+    """
+    One parameter is converted to a series of ParsedDocstrings. 


This docstring is untrue and should be rephrased and put as a comment instead. This is arguably an implementation detail.

tristanlatr · 2024-11-17T17:30:53Z

pydoctor/templatewriter/pages/__init__.py

                fallback=epydoc2stan.colorized_pyval_fallback, 
                section='rendering of class signature')
            r.extend(stan.children)

        r.append(')')
    return r

+LONG_SIGNATURE = 120 # this doesn't acount for the 'def ' and the ending ':'


The question is should we provide yet another CLI option to customize the threshold from which a function def is considered long?

120 chars might sounds like a good heuristic. But what if the function is overloaded and has 15 parameters for each overload? This behavior suddenly becomes worse than before since users will have to scroll down a lot more to get to the core of the docstring… an idea would be to yet have a third presentation when the function def length it’s more than, say, 8 times a long function (960 chars): in this scenario, the signatures are not wrapped into separate lines automatically and a button is added to toofle the line wrapping

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.

This comment has been minimized.

Sign in to view

tristanlatr added 3 commits October 25, 2024 15:58

Some more adjustments. Make the self param always inline. Try to opti…

0b7c76e

…miza a little the _colorize_signature() function.

Add comment

188c410

Fix usage of cache

83d47f7

This comment has been minimized.

Sign in to view

Fix usages of cache

ab1cdd1

This comment has been minimized.

Sign in to view

tristanlatr added 3 commits October 25, 2024 18:04

Simplify with_linker() and with_tag(). These do not create new parsed…

eca5ced

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

Revert "Simplify with_linker() and with_tag(). These do not create ne…

ff4269f

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

Minor changes not to use lru_cache too much

914e01c

This comment has been minimized.

Sign in to view

Try to optimize what I can

cdef965

This comment has been minimized.

Sign in to view

tristanlatr and others added 3 commits October 26, 2024 00:32

Fix mypy

2033d65

Merge branch 'master' into 801-signature-spans

5396396

Remove unused imports

282250b

This comment has been minimized.

Sign in to view

tristanlatr added 2 commits October 29, 2024 15:12

Better implementation of with_linker and with_tag inside a single sub…

6a4de9f

…class. Introduce ParsedDocstring.to_text().

First attempt to implement relatively smart Expand/Collapse signature…

c0f93dc

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

This comment has been minimized.

Sign in to view

Simplify things: don't try to wrap overload signatures. Sphinx doesn'…

da89d7c

…t try to do such things either...

This comment has been minimized.

Sign in to view

tristanlatr added 2 commits November 14, 2024 14:18

Get rid of the ParsedStanOnly by using parsed_text_with_css instead.

141b211

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

Few simplifications here and there.

a46a3a3

tristanlatr added 3 commits November 14, 2024 14:58

Use the CSS class 'decorator' for all decorators.

40ac0a6

Fix various bugs in the implementation.

4172485

also remove the summary caching on the parsed docstring side, this is unnecessary because it's already cahed in the documentable.

Fix pyflakes

7103ce5

This comment has been minimized.

Sign in to view

Fix format_undocumented_summary returning a tuple of strings instead …

eae961a

…of a string. A some annotation.

This comment has been minimized.

Sign in to view

increase the threshold for a function to be rendered in several lines.

7c6c6eb

This comment has been minimized.

Sign in to view

tristanlatr added 3 commits November 14, 2024 17:16

Avoid an empty div for decorators when there are no decorators.

19400ff

Use non breaking spaces in sugnature defs.

a3ebbdf

Improve a little bit the rendering of parameter tables that uses very…

cd257eb

… long annotations.

This comment has been minimized.

Sign in to view

Merge branch 'master' into 801-signature-spans

977e5b5

This comment has been minimized.

Sign in to view

tristanlatr added 2 commits November 18, 2024 09:18

Change comment

91edc51

Merge branch '801-signature-spans' of github.com:twisted/pydoctor int…

b504c21

…o 801-signature-spans

This comment has been minimized.

Sign in to view

tristanlatr added 2 commits November 21, 2024 11:56

Add an environment to build temporalio docs

25b5e62

Add a bug overload in the google demo

bd2de92

tristanlatr changed the title ~~Signatures improvments~~ Wrap signatures onto several lines when function len is over a treshold Nov 21, 2024

tristanlatr commented Nov 26, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Wrap signatures onto several lines when function len is over a treshold #831

Wrap signatures onto several lines when function len is over a treshold #831

tristanlatr commented Oct 25, 2024 •

edited

Loading

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

codecov bot commented Oct 25, 2024 •

edited

Loading

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

github-actions bot commented Nov 21, 2024

tristanlatr Nov 14, 2024

tristanlatr Nov 14, 2024

tristanlatr Nov 16, 2024

tristanlatr Nov 16, 2024

tristanlatr Nov 16, 2024

tristanlatr Nov 16, 2024

tristanlatr Nov 16, 2024

tristanlatr Nov 16, 2024

tristanlatr Nov 16, 2024

tristanlatr Nov 17, 2024

	fromdocutils = ''.join(node2stan.gettext(doc.to_node()))
	fromdocutils = doc.to_text()

	class WrappedParsedDocstring(ParsedDocstring):
	class _WrappedParsedDocstring(ParsedDocstring):

	CSS auto layour table algo not to create tables
	CSS auto layout table algo not to create tables

	defined varaible rather the nested definitions when there are name colisions.
	defined variables rather the nested definitions when there are name collisions.

Wrap signatures onto several lines when function len is over a treshold #831

Are you sure you want to change the base?

Wrap signatures onto several lines when function len is over a treshold #831

Conversation

tristanlatr commented Oct 25, 2024 • edited Loading

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

codecov bot commented Oct 25, 2024 • edited Loading

Codecov Report

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

github-actions bot commented Nov 21, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tristanlatr commented Oct 25, 2024 •

edited

Loading

codecov bot commented Oct 25, 2024 •

edited

Loading