sphinx-doc / sphinx-doc/sphinx

Inconsistent type references when using autodoc

Open
#7,972 4 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

I have the following python code:

"""My Implementation"""
from typing import Collection

from sphinx_autodoc.api import MyInterfaceClass


class MyClass:  # pylint: disable=too-few-public-methods
    """This is my class and its doc
    
    This is a reference to :class:`~sphinx_autodoc.api.MyInterfaceClass`
    
    """

    delegate: MyInterfaceClass
    """Some delegate"""

    external: Collection
    """Some external reference"""

    def get_delegate(self) -> MyInterfaceClass:
        """Gets the delegate

        Returns:
            the delegate
        """
        return self.delegate

    def get_external(self) -> Collection:
        """Gets the delegate

        Returns:
            the delegate
        """
        return self.external


VARIABLE: MyClass = MyClass()
"""This is my variable and its doc"""

When producing a Sphinx documentation with the following config:

extensions = [
    'sphinx.ext.intersphinx',
    'sphinx.ext.napoleon',
    'sphinx_autodoc_typehints',
    'sphinx.ext.autodoc'
]

# Some config
intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

I see the following unexpected behaviour:

To Reproduce

I have created a small test repo to illustrate and reproduce the issue:

  • clone https://github.com/Carsten-Leue/sphinx-autodoc
  • install tox
  • run tox -e doc

The result of this step is also checked in at https://github.com/Carsten-Leue/sphinx-autodoc/tree/master/build/docs

Expected behavior

  • Linking to types in my own project (across submodules) works consistently, everywhere where a type gets referenced, i.e. in types for arguments, return values, variables and refences in doc strings

Your project

https://github.com/Carsten-Leue/sphinx-autodoc

Environment info

  • OS: Windoes 10
  • Python version: Python 3.8.4 (tags/v3.8.4:dfa645a, Jul 13 2020, 16:46:45) [MSC v.1924 64 bit (AMD64)] on win32
  • Sphinx version: 3.1.2
  • Sphinx extensions: ['sphinx.ext.intersphinx',
    'sphinx.ext.napoleon',
    'sphinx_autodoc_typehints',
    'sphinx.ext.autodoc']

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

Clone the linked reproduction repository and run tox -e doc; inspect the generated pages under build/docs and compare links for class docstrings, properties, return values, and the global variable. Trace the autodoc and sphinx_autodoc_typehints handling for these references, then verify that equivalent project and external type references render consistently.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.