Wrap signatures onto several lines when function len is over a treshold and function has the focus #831
Conversation
…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.
This comment has been minimized.
This comment has been minimized.
…miza a little the _colorize_signature() function.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
Codecov ReportAttention: Patch coverage is
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. 🚀 New features to boost your workflow:
|
This comment has been minimized.
This comment has been minimized.
… 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.
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.
2 similar comments
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
…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.
This comment has been minimized.
This comment has been minimized.
…t try to do such things either...
This comment has been minimized.
This comment has been minimized.
Fix some cyclic imports issue as a drive-by change: model.Documentable was uncessarly runtime imported inside restructuredtext and epydoc parsers.
|
@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. |
|
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 |
| def colorize_pyval(pyval: Any, linelen:Optional[int], maxlines:int, | ||
| linebreakok:bool=True, refmap:Optional[Dict[str, str]]=None, | ||
| is_annotation: bool = False) -> ColorizedPyvalRepr: |
There was a problem hiding this comment.
should we be adopting Black so that this sort of style change doesn't require discretion? :)
|
According to pydoctor_primer, this change doesn't affect pydoctor warnings on a corpus of open source code. ✅ |
| def colorize_pyval(pyval: Any, linelen:Optional[int], maxlines:int, | ||
| linebreakok:bool=True, refmap:Optional[Dict[str, str]]=None, | ||
| is_annotation: bool = False) -> ColorizedPyvalRepr: |
|
According to pydoctor_primer, this change doesn't affect pydoctor warnings on a corpus of open source code. ✅ |
pydoctor/astbuilder.py
Outdated
| # Craft an invalid signature that does not look like a function with zero arguments. | ||
| signature = Signature( | ||
| [Parameter(InvalidSignatureParamName('...'), | ||
| kind=Parameter.POSITIONAL_OR_KEYWORD)]) |
There was a problem hiding this comment.
This should be None and then we render it like (...) in the templatewriter
|
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.
|
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
|
According to pydoctor_primer, this change doesn't affect pydoctor warnings on a corpus of open source code. ✅ |
| @@ -328,6 +343,7 @@ def switch_context(self, ob:Optional['Documentable']) -> ContextManager[None]: | |||
| in this case error will NOT be reported at all. | |||
| """ | |||
|
|
|||
|
|
|||
There was a problem hiding this comment.
| @@ -2,6 +2,7 @@ | |||
|
|
|||
| from logging import LogRecord | |||
| from typing import Iterable, TYPE_CHECKING, Sequence | |||
|
|
|||
There was a problem hiding this comment.
|
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)
|
|
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)
|
This change fixes #801.
Signature.__str__(), which we don't need anymore because we're computing the representation ourselve.Examples:
The way to get the old behaviour back is to use the following custom css: