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.

Parameters html are divided into .rst-sig-param or .rst-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.
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:

.rst-sig-param, .rst-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 97.79006% with 4 lines in your changes missing coverage. Please review.

Project coverage is 92.85%. Comparing base (8bf1ec8) to head (05a7794).
Report is 12 commits behind head on master.

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

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #831      +/-   ##
==========================================
+ Coverage   92.79%   92.85%   +0.06%     
==========================================
  Files          47       47              
  Lines        8470     8528      +58     
  Branches     1549     1573      +24     
==========================================
+ Hits         7860     7919      +59     
+ Misses        350      348       -2     
- Partials      260      261       +1

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

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

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

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!

docs/google_demo/__init__.py

pydoctor/epydoc/markup/__init__.py

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

pydoctor/epydoc/markup/_types.py

pydoctor/templatewriter/search.py

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

pydoctor/themes/base/apidocs.css

pydoctor/themes/readthedocs/readthedocstheme.css

pydoctor/themes/base/apidocs.css

pydoctor/epydoc/markup/__init__.py

docs/google_demo/__init__.py

pydoctor/epydoc/markup/_types.py

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

pydoctor/epydoc/markup/__init__.py

pydoctor/epydoc2stan.py

github-actions · 2025-02-20T00:15:35Z

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

tristanlatr · 2025-02-20T00:55:50Z

pydoctor/astbuilder.py

+            # Craft an invalid signature that does not look like a function with zero arguments.
+            signature = Signature(
+                [Parameter(InvalidSignatureParamName('...'), 
+                           kind=Parameter.POSITIONAL_OR_KEYWORD)])


This should be None and then we render it like (...) in the templatewriter

github-actions · 2025-02-20T01:08:37Z

Diff from pydoctor_primer, showing the effect of this PR on open source code:

numpy (https://github.com/numpy/numpy): typechecking got 1.06x slower (180.5s -> 190.6s)
(Performance measurements are based on a single noisy sample)

twisted (https://github.com/twisted/twisted): typechecking got 1.10x slower (217.2s -> 237.9s)
(Performance measurements are based on a single noisy sample)

…ace that by docutils node manipulations.

github-actions · 2025-02-28T04:53:21Z

Diff from pydoctor_primer, showing the effect of this PR on open source code:

numpy (https://github.com/numpy/numpy): typechecking got 1.05x slower (199.9s -> 210.8s)
(Performance measurements are based on a single noisy sample)

twisted (https://github.com/twisted/twisted): typechecking got 1.05x slower (264.6s -> 278.2s)
(Performance measurements are based on a single noisy sample)

…o 801-signature-spans

github-actions · 2025-02-28T14:18:51Z

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

tristanlatr

Few whitespace changes I don't underdstand and we'll be good

pydoctor/epydoc/markup/plaintext.py

pydoctor/epydoc/markup/restructuredtext.py

pydoctor/epydoc/markup/google.py

pydoctor/epydoc/markup/_napoleon.py

tristanlatr · 2025-02-28T04:33:22Z

pydoctor/epydoc/markup/__init__.py

        in this case error will NOT be reported at all.
        """

+


Suggested change

pydoctor/epydoc2stan.py

tristanlatr · 2025-02-28T04:40:01Z

pydoctor/test/__init__.py


 from logging import LogRecord
 from typing import Iterable, TYPE_CHECKING, Sequence
+


Suggested change

pydoctor/test/__init__.py

github-actions · 2025-02-28T14:32:05Z

Diff from pydoctor_primer, showing the effect of this PR on open source code:

sphinx (https://github.com/sphinx-doc/sphinx): typechecking got 1.11x slower (168.7s -> 187.1s)
(Performance measurements are based on a single noisy sample)

numpy (https://github.com/numpy/numpy): typechecking got 1.06x slower (212.3s -> 225.7s)
(Performance measurements are based on a single noisy sample)

github-actions · 2025-02-28T14:36:04Z

Diff from pydoctor_primer, showing the effect of this PR on open source code:

sphinx (https://github.com/sphinx-doc/sphinx): typechecking got 1.07x slower (180.5s -> 193.5s)
(Performance measurements are based on a single noisy sample)

sdk-python (https://github.com/temporalio/sdk-python): typechecking got 1.06x slower (178.0s -> 188.9s)
(Performance measurements are based on a single noisy sample)

twisted (https://github.com/twisted/twisted): typechecking got 1.07x slower (236.5s -> 251.9s)
(Performance measurements are based on a single noisy sample)

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.