sphinx-doc / sphinx-doc/sphinx

autodoc_typehints="description" doesn't fully resolve constructor type hints from type comments

Open
#8,243 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autodoc type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug
When autodoc_typehints="description", type hint comments for classes aren't fully resolved, even with autoclass_content="both".

To Reproduce
Create module.py with these contents:

from typing import Optional

Maybe = Optional

class MaybeInt(object):
    """:param value: The value to hold"""
    def __init__(self, value):
        # type: (Maybe[int]) -> None
        self.value = value

    def get_value(self):
        # type: () -> Maybe[int]
        """:return: The held value"""
        return self.value

Create index.rst with these contents:

.. automodule:: module
   :members:

Generate docs twice in plain text format twice, once with autodoc_typehints="description" and once with autodoc_typehints="signature".

python3.8 -msphinx -aE -C -b text -D 'extensions=sphinx.ext.autodoc' -D autoclass_content=both -D autodoc_typehints=description . description
python3.8 -msphinx -aE -C -b text -D 'extensions=sphinx.ext.autodoc' -D autoclass_content=both -D autodoc_typehints=signature . signature

And note that signature/index.txt has:

class module.MaybeInt(value)

   Parameters:
      **value** (*Maybe**[**int**]*) -- The value to hold

   Return type:
      None

   get_value()

      Returns:
         The held value

      Return type:
         Optional[int]

In the case of the return type from get_value, the Maybe was resolved by typing.get_type_hints to be Optional. In the case of the parameter to the constructor, the Maybe was not able to be resolved.

When autodoc_typehints="signature", both were successfully resolved to Optional.

Expected behavior

Type hints should be fully resolved.

Environment info

  • OS: Linux
  • Python version: 3.8.5
  • Sphinx version: 3.2.1
  • Sphinx extensions: sphinx.ext.autodoc

Additional context

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the issue with the provided module.py, index.rst, and Sphinx commands, then trace the autodoc handling for constructor type comments under autodoc_typehints="description". Done means the constructor parameter type resolves Maybe to Optional consistently with the signature output.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.