sphinx-autodoc-typehints icon indicating copy to clipboard operation
sphinx-autodoc-typehints copied to clipboard

rtype not separated from previous paragraph

Open tjsmart opened this issue 1 year ago • 1 comments

I've run into a situation where sphinx-autodoc-typehints is inserting the rtype signature without creating space between rtype and the previous paragraph so it isn't being rendered correctly in the final html output:

image

Instead what I expected to see is:

expected

I am using sphinx-autodoc-typehints==2.0.0.


To help, I've created a repository with a MRE here: https://github.com/tjsmart/sphinx-autodoc-typehints-rtype-issue.

I'm not sure I understand enough about the codebase but it seems to me the problematic area is inside _inject_rtype.

I noticed a related ticket from a few years ago introduced these lines of code:

    if insert_index == len(lines) and not r.found_param:
        # ensure that :rtype: doesn't get joined with a paragraph of text
        lines.append("")
        insert_index += 1

I wonder if it would be better to just explicitly check if the previous line is not blank. If it isn't then insert a blank line to make sure that rtype won't be joined with the previous paragraph of text. For example we could change these lines to be:

    if insert_index > 0 and insert_index <= len(lines) and lines[insert_index-1]:
        # ensure that :rtype: doesn't get joined with a paragraph of text
        lines.insert(insert_index, "")
        insert_index += 1

tjsmart avatar Mar 01 '24 23:03 tjsmart

I wonder if it would be better to just explicitly check if the previous line is not blank. If it isn't then insert a blank line to make sure that rtype won't be joined with the previous paragraph of text.

That sounds reasonable, if you add a test validating test a PR is welcome.

gaborbernat avatar Mar 02 '24 03:03 gaborbernat