-
Notifications
You must be signed in to change notification settings - Fork 1.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: Fix truncated summary line #3235
Conversation
|
||
# Extract until the first blank line if any. | ||
try: | ||
doc = doc[:doc.index('')] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this correct?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If doc
does not have ''
, index()
will raise ValueError
(thus doc
is not modified).
If it does, index()
returns the index of ''
, so this statement extracts elements up until ''
, if any.
>>> a = ['a', 'b', 'c']
>>> a[:a.index('b')]
['a']
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OK, I understand.
LGTM! |
doc: Fix truncated summary line
Fixes #3234.
The problem is in autosummary's algorithm on parsing docstring: https://github.com/sphinx-doc/sphinx/blob/1.6.3/sphinx/ext/autosummary/__init__.py#L341
It treats the substring which ends with a period followed by a space (or a EOL) as the "first sentence", which trucate the string at e.g. "a.k.a. SOMETHING".
This PR interferes that algorithm by placing
\
followed by an extra space before the existing space, which translates to an empty string. (I'm not sure if this is the correct use of the sequence. But at least it works)Additionally I put a code to check if docstrings are compliant with autosummary's algorithm.
TODO: Port to CuPy