readthedocs / sphinx-autoapi

A new approach to API documentation in Sphinx.
https://sphinx-autoapi.readthedocs.io/
MIT License
415 stars 126 forks source link

Reference target not found if using pipe for Union #366

Closed spagh-eddie closed 1 year ago

spagh-eddie commented 1 year ago

I have made an MRE for an error I am getting:

/Users/.../test/docs/autoapi/test/index.rst:38: WARNING: py:class reference target not found: Path

I have found that this issue is due to using Path | None in a type annotation. This issue goes away if I use one pathlib.Path | None, Optional[Path], or Union[Path, None].

Screen Shot 2023-01-31 at 10 16 37 AM

To reproduce:

% tree            
.
├── docs
│   ├── Makefile
│   ├── conf.py
│   └── index.rst
└── src
    └── test
        └── __init__.py
# __init__.py
import pathlib
from pathlib import Path
from typing import Optional, Union

def simple(self, p: Path):
    """This is OK"""

def optional(self, p: Optional[Path]):
    """This is OK"""

def union(self, p: Union[Path, None]):
    """This is OK"""

def pipe(self, p: Path | None):
    """This fails autoapi unless use ``pathlib.Path | None`` instead"""
# conf.py
import pathlib
import sys

_project_dir = pathlib.Path(__file__).parents[1]
_src_dir = _project_dir / "src"
sys.path.insert(0, _src_dir.as_posix())

extensions = ["sphinx.ext.intersphinx", "autoapi.extension"]

intersphinx_mapping = {"python": ("https://docs.python.org/3.10", None)}
intersphinx_timeout = 10

autoapi_dirs = [_src_dir / "test"]
autoapi_keep_files = False
SPHINXOPTS    += -T --color -W --keep-going -n
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = .
BUILDDIR      = build

%: Makefile
    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)