search

tox-dev / sphinx-autodoc-typehints

Type hints support for the Sphinx autodoc extension
MIT License
556 stars 105 forks source link

Invalid spacing between `:rtype:` and following directives #293

Closed jakelishman closed 1 year ago

jakelishman commented 1 year ago

In the 1.21.0 release, the position of the emitted :rtype: field seems to have changed so that it is now earlier in the docstring, rather than reliably being at the end. This is fine, except when the place the injector chooses to place it is immediately before a .. <whatever>:: directive. There doesn't seem to reliable be a blank line inserted after it, and if not, Sphinx complains that the field list ends unexpectedly.

For example, given this Python file tmp/__init__.py:

def my_function() -> None:
    """
    .. rubric:: Notes

    Hello, world.
    """

and this Sphinx conf.py:

project = 'tmp'
extensions = [
    "sphinx.ext.autodoc",
    "sphinx_autodoc_typehints",
]

running Sphinx's make html gives:

Running Sphinx v6.1.3
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] index
/Users/jake/tmp/autodoc-typehints/pkg/tmp/__init__.py:docstring of tmp.my_function:1: WARNING: Field list ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex py-modindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The docstring enters _inject_types_to_docstring as

.. rubric:: Notes

Hello, world.

and is modified to

:rtype: :py:obj:`None`
.. rubric:: Notes

Hello, world.

This also happens if there's any regular text before the .. rubric:: notes as well (which is a bit more of a realistic scenario).

jakelishman commented 1 year ago

This behaviour was added in #290, which did add a test in test_sphinx_output, but this test causes Sphinx to emit the same warning mentioned in this issue which doesn't cause a test failure.

gaborbernat commented 1 year ago

It seems @hoodmane this was a regression introduced.

hoodmane commented 1 year ago

Oops didn't notice the warning. I guess the fix is simple enough.

As an aside, it occurs to me that this code would all be a lot simpler if we could manipulate a tree instead of strings containing a whitespace-sensitive markup format...

gaborbernat commented 1 year ago

@jakelishman, this broke https://github.com/tox-dev/pyproject-api/actions/runs/3933433212. Can you take a look, please?

jakelishman commented 1 year ago

I think your CI run there is broken by 1.21.0 and fixed by the PR of mine you just merged (and the 1.21.1 release you just cut, thanks!). Could you try re-running your CI? I was unable to reproduce the failure locally with 1.21.1, but could if I pinned sphinx-autodoc-typehints to 1.21.0.