Signatures improvments #831

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

This change fixes #801:

Parameters html are divided into .sig-param or .sig-symbol spans.
When the function is long enough 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.

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

Project coverage is 92.09%. Comparing base (129f930) to head (c0f93dc).

Files with missing lines	Patch %	Lines
pydoctor/templatewriter/pages/__init__.py	59.57%	13 Missing and 6 partials ⚠️
pydoctor/epydoc2stan.py	92.45%	4 Missing and 4 partials ⚠️
pydoctor/epydoc/markup/__init__.py	96.15%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #831      +/-   ##
==========================================
- Coverage   92.29%   92.09%   -0.20%     
==========================================
  Files          47       47              
  Lines        8514     8696     +182     
  Branches     1695     1739      +44     
==========================================
+ Hits         7858     8009     +151     
- Misses        385      406      +21     
- Partials      271      281      +10

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

github-actions · 2024-10-29T19:26:09Z

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

sphinx (https://github.com/sphinx-doc/sphinx): typechecking got 1.05x slower (197.7s -> 208.4s)
(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.