TypeVar object not documented as expected in method signature

Viewed 239

The problem

I'm wanting to document some modules in a package I'm developing using Sphinx. Throughout the modules I've imported some TypeVar objects from a module within the package - these objects refer to different types of data objects. I've done this mainly so that I can use Pandas and Koalas dataframes within a given module without having to import Pandas/Koalas just for the type hints.

When I run sphinx to document the modules, I expect the value assigned to the TypeVar object to be displayed. However, I get the module where the TypeVar object is stored, plus the value assigned to the TypeVar object.

How to Reproduce

Let's say I have the following package structure:

example_package
├── __init__.py
├── example_module
│   ├── __init__.py
│   └── example_module.py
└── typevar_objects
    ├── __init__.py
    └── typevar_objects.py

I keep my TypeVar objects in typevar_objects.py:

from typing import TypeVar

PandasDataFrameType = TypeVar('pandas.core.frame.DataFrame')

Then in my module example_module.py, I import the TypeVar object as shown:

from typevar_objects import PandasDataFrameType

class A:
    def some_func(self, df: PandasDataFrameType):
        return None

Using the following settings in conf.py:

import os
import sys
import example_package

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx.ext.imgmath',
    'sphinx.ext.autosummary',
]

autodoc_member_order = "bysource"
autodoc_default_options = {
    "members": True,
    'undoc-members': True,
    'member-order': 'bysource',
}
autodoc_typehints = 'signature'
templates_path = ['_templates']
language = 'en'
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
todo_include_todos = True
master_doc = 'index'
numpydoc_show_class_members = False
autosummary_generate = True
panels_add_bootstrap_css = False
html_use_index = False
html_domain_indices = False
html_static_path = ['_static']

I run sphinx on the package using the commands:

rm -r doc
sphinx-apidoc -F -M -d 1 --separate -o doc example_package
cp conf.py doc
cd doc
make clean
make html

Expected behavior

I would expect the documentation for A.some_func to show df: pandas.core.frame.DataFrame. However, it instead shows df: example_package.typevar_objects.pandas.core.frame.DataFrame:

Documentation for A.some_func()

Here's a link to a zipped version of the example project:

Example project

0 Answers
Related