2

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

mzjn
  • 48,958
  • 13
  • 128
  • 248
James Laidler
  • 21
  • 1
  • 1
    Do you just want to avoid the overhead of importing pandas? Maybe you can try to mock pandas by adding `autodoc_mock_imports = ["pandas"]` in conf.py. https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports – mzjn Dec 17 '21 at 14:19
  • @mzjn thanks for your input - would that mean that in the module, I would use the type hint `pandas.core.frame.DataFrame`, but not import pandas in the module itself (and instead use `autodoc_mock_imports = ["pandas"]` in the conf.py file)? – James Laidler Dec 20 '21 at 08:21
  • You'll need have an import statement for DataFrame in the module. – mzjn Dec 20 '21 at 09:09
  • But then I might as well just import pandas in the module and do the type hint using the import directly. I need a way to not import pandas but have a type hint that corresponds to the pd.core.frame.DataFrame object. – James Laidler Dec 22 '21 at 14:01
  • If you use `autodoc_mock_imports = ["pandas"]`, Pandas will not really be imported. What gets "imported" is a mock object that simulates Pandas and allows you to use `DataFrame` in the type hint. – mzjn Dec 22 '21 at 15:18
  • But would the module not fail when running, as I'd reference pd.core.frame.DataFrame in the code itself? – James Laidler Dec 23 '21 at 15:55
  • I think I misunderstood what you want. Sphinx 4.4 (not released yet) includes a new option, `autodoc_typehints_format`. Setting it to "short" is perhaps good enough for you. https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_typehints_format – mzjn Jan 04 '22 at 11:34
  • @mzjn yeah I think that should work - do you know when 4.4 will be released? – James Laidler Jan 05 '22 at 09:20
  • @mzjn I've updated to 4.4.0, but it still isn't working. I use the `autoclass` directive for documenting my classes, but the `autodoc_typehints_format` doesn't seem to be a configuration that can be set. Is there a way to set this for `autoclass`? – James Laidler Jan 19 '22 at 16:21
  • Setting `autodoc_typehints_format = "short"` in conf.py works for me. – mzjn Jan 19 '22 at 22:04

0 Answers0