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 (8b24212).

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

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 and others added 2 commits December 13, 2024 13:26

Merge branch 'master' into 801-signature-spans

07fc41d

Fix the NotFoundLinker

668f4d0

tristanlatr marked this pull request as ready for review December 13, 2024 18:30

Do not mark overloaded functions with css class .long-signature

7fc2b10

This comment has been minimized.

Sign in to view

Remove unused imports

80de043

This comment has been minimized.

Sign in to view

Add readme entries

a9c5bf2

This comment has been minimized.

Sign in to view

Upadate docs tests

6784e4c

This comment has been minimized.

Sign in to view

tristanlatr added 2 commits December 13, 2024 13:53

Like back, consider a function long from 88 chars.

78f73b9

Adjust test again

bf7045f

This comment has been minimized.

Sign in to view

tristanlatr commented Dec 13, 2024

View reviewed changes

README.rst Show resolved Hide resolved

Update README.rst

a37b028

tristanlatr commented Dec 15, 2024

View reviewed changes

tristanlatr commented Jan 10, 2025

View reviewed changes

Merge branch 'master' into 801-signature-spans

8b24212

tristanlatr requested review from a team January 14, 2025 18:32

tristanlatr changed the title ~~Wrap signatures onto several lines when function len is over a treshold~~ Wrap signatures onto several lines when function len is over a treshold and function has the focus Jan 15, 2025

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 and function has the focus #831

Wrap signatures onto several lines when function len is over a treshold and function has the focus #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 Dec 13, 2024

tristanlatr Dec 15, 2024

tristanlatr Jan 10, 2025

github-actions bot commented Jan 14, 2025

tristanlatr commented Jan 18, 2025

glyph commented Jan 22, 2025

tristanlatr commented Jan 23, 2025

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

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

Are you sure you want to change the base?

Wrap signatures onto several lines when function len is over a treshold and function has the focus #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 Dec 13, 2024

tristanlatr Dec 15, 2024

Choose a reason for hiding this comment

tristanlatr Jan 10, 2025

Choose a reason for hiding this comment

github-actions bot commented Jan 14, 2025

tristanlatr commented Jan 18, 2025

glyph commented Jan 22, 2025

tristanlatr commented Jan 23, 2025

tristanlatr commented Oct 25, 2024 •

edited

Loading

codecov bot commented Oct 25, 2024 •

edited

Loading