tox-dev / sphinx-autodoc-typehints

Type hints support for the Sphinx autodoc extension
MIT License
560 stars 106 forks source link

rtype not separated from previous paragraph #431

Open tjsmart opened 8 months ago

tjsmart commented 8 months ago

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
gaborbernat commented 8 months ago

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.