sphinx-doc / sphinx-doc/sphinx

autodoc typehints fail to resolve types when a function parameter is assigned a default value that is an enum value.

Open
#8,218 2 comments 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 using automodule, if a function parameter is an enum and is assigned a default value, all parameters appear to fail to process.

To Reproduce

Simple doc file index.rst:

Hello World
===========

code docs
=========

.. automodule:: helloworld.helloworld
    :members:
    :undoc-members:
    :show-inheritance:

Here's an example module helloworld.py:

from enum import Enum

class MyEnum(Enum):
    FIRST = 1
    SECOND = 2
    THIRD = 3

class OtherClass():
    pass

class Example1:
    """Parameter types link correctly here"""
    def __init__(self,
                 param1: OtherClass,
                 param2: MyEnum):
        pass

    def foo(self,
            param1: OtherClass,
            param2: MyEnum):
        pass

class Example2:
    """When an enum is assigned a default value no type links are resolved"""
    def __init__(self,
                 param1: OtherClass,
                 param2: MyEnum = MyEnum.FIRST):
        pass

    def foo(self,
            param1: OtherClass,
            param2: MyEnum = MyEnum.FIRST):
        pass

class Example3:
    """When an enum is assigned a default value no type links are resolved"""
    def __init__(self,
                 param1: OtherClass,
                 param2: MyEnum = MyEnum(1)):
        pass

Expected behavior
I expect the enum types to resolve correctly and link to the enum definition.
I expect the other parameters to also resolve their types and link their definitions as well.
A nice-to-have would be for the enum value link to the value in the enum definition as well.

Your project
I've included a simple example above

Screenshots
Here's the generated documentation. See how Example1 resolves the types correctly but Example2 does not.
image

Environment info

  • OS: Ubuntu 18.04, Ubuntu 20.04
  • Python version: 3.6.9, 3.8.2
  • Sphinx version: 3.1.2, 3.2.1
  • Sphinx extensions: sphinx.ext.autodoc
  • Extra tools: Viewing output on Chrome

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

Reproduce the issue with the supplied index.rst and helloworld.py examples, comparing Example1 with Example2 and Example3. Trace Sphinx autodoc's type-hint resolution from the automodule entry point; done means enum parameter types and the other parameter types link to their definitions when defaults are present.

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
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.