Autodoc attempts to resolves strings in Literal() to references in 5.0

[wjones127]

Describe the bug

Starting in 5.0, we get an error processing these lines for autodoc:

def write_deltalake(
    ...
    mode: Literal["error", "append", "overwrite", "ignore"] = "error",
    ...
):

https://github.com/delta-io/delta-rs/blob/5a293dd5e899167944cdb447599ed5f3f8916a22/python/deltalake/writer.py#L65

with the warning (treated as error):

 /home/runner/work/delta-rs/delta-rs/python/deltalake/writer.py:docstring of deltalake.writer.write_deltalake::py:class reference target not found: 'error'

If I modify the function signature to

def write_deltalake(
    ...
    mode: Literal["append", "overwrite", "ignore"] = "append",
    ...
):

I get the error

/home/wjones/delta-rs/python/venv/lib/python3.10/site-packages/deltalake/writer.py:docstring of deltalake.writer.write_deltalake::py:class reference target not found: 'append'

so I feel pretty sure it's looking at those string values.

How to Reproduce

$ git clone https://github.com/delta-io/delta-rs.git
$ cd delta-rs/python
$ make setup-venv
$ source venv/bin/activate
$ make build-documentation

See CI run:
https://github.com/delta-io/delta-rs/runs/6659471490?check_suite_focus=true

Expected behavior

Renders without warning, not attempting to resolve those strings as some class reference. I've tested locally on MacOS and Linux and it works fine on versions 4.3 and 4.5. We have not changed that line since it was last published: https://delta-io.github.io/delta-rs/python/api_reference.html#writing-deltatables

Your project

https://delta-io.github.io/delta-rs/python/api_reference.html#writing-deltatables

Screenshots

No response

OS

Linux and MacOS

Python version

3.10

Sphinx version

5.0.0

Sphinx extensions

sphinx.ext.autodoc

Extra tools

No response

Additional context

No response

[wjones127]

Might be identical to: #9775

[AA-Turner]

Running the following

import shutil
from pathlib import Path

from sphinx.cmd.make_mode import run_make_mode


def write(filename, text): Path(filename).write_text(text, encoding="utf-8")


write("bug.py", '''\
from typing import Literal

def write_deltalake(mode: Literal["error", "append"] = "error"): ...
''')

write("conf.py", '''\
import os, sys
sys.path.insert(0, os.path.abspath("."))
extensions = ['sphinx.ext.autodoc']
nitpicky = True
''')

write("index.rst", '''\
.. autofunction:: bug.write_deltalake
''')

shutil.rmtree("_build", ignore_errors=True)
run_make_mode(["html", ".", "_build", "-T", "-W"])

as python reproducer_10497.py, I can't reproduce the error. Please could you try to write a similar minimal reproducer that still raises the warning?

A

[wjones127]

Thanks for the script @AA-Turner. I confirm that your script doesn't reproduce the error, but if I add the line autodoc_typehints = "description", then I can:

import shutil
from pathlib import Path

from sphinx.cmd.make_mode import run_make_mode


def write(filename, text): Path(filename).write_text(text, encoding="utf-8")


write("bug.py", '''\
from typing import Literal

def write_deltalake(mode: Literal["error", "append"] = "error"): ...
''')

write("conf.py", '''\
import os, sys
sys.path.insert(0, os.path.abspath("."))
extensions = ['sphinx.ext.autodoc']
autodoc_typehints = "description"
nitpicky = True
''')

write("index.rst", '''\
.. autofunction:: bug.write_deltalake
''')

shutil.rmtree("_build", ignore_errors=True)
run_make_mode(["html", ".", "_build", "-T", "-W"])

Does that also work for you?

full output

❯ python reproducer_10497.py
Running Sphinx v5.0.0
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index                                         
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                          

Traceback (most recent call last):
  File "/Users/willjones/Documents/code_projects/delta-rs/python/venv/lib/python3.9/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app.build(args.force_all, filenames)
  File "/Users/willjones/Documents/code_projects/delta-rs/python/venv/lib/python3.9/site-packages/sphinx/application.py", line 329, in build
    self.builder.build_update()
  File "/Users/willjones/Documents/code_projects/delta-rs/python/venv/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 288, in build_update
    self.build(to_build,
  File "/Users/willjones/Documents/code_projects/delta-rs/python/venv/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 352, in build
    self.write(docnames, list(updated_docnames), method)
  File "/Users/willjones/Documents/code_projects/delta-rs/python/venv/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 544, in write
    self._write_serial(sorted(docnames))
  File "/Users/willjones/Documents/code_projects/delta-rs/python/venv/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 554, in _write_serial
    self.write_doc(docname, doctree)
  File "/Users/willjones/.pyenv/versions/3.9.9/lib/python3.9/contextlib.py", line 126, in __exit__
    next(self.gen)
  File "/Users/willjones/Documents/code_projects/delta-rs/python/venv/lib/python3.9/site-packages/sphinx/util/logging.py", line 217, in pending_warnings
    memhandler.flushTo(logger)
  File "/Users/willjones/Documents/code_projects/delta-rs/python/venv/lib/python3.9/site-packages/sphinx/util/logging.py", line 182, in flushTo
    logger.handle(record)
  File "/Users/willjones/.pyenv/versions/3.9.9/lib/python3.9/logging/__init__.py", line 1599, in handle
    self.callHandlers(record)
  File "/Users/willjones/.pyenv/versions/3.9.9/lib/python3.9/logging/__init__.py", line 1661, in callHandlers
    hdlr.handle(record)
  File "/Users/willjones/.pyenv/versions/3.9.9/lib/python3.9/logging/__init__.py", line 948, in handle
    rv = self.filter(record)
  File "/Users/willjones/.pyenv/versions/3.9.9/lib/python3.9/logging/__init__.py", line 806, in filter
    result = f.filter(record)
  File "/Users/willjones/Documents/code_projects/delta-rs/python/venv/lib/python3.9/site-packages/sphinx/util/logging.py", line 425, in filter
    raise exc
sphinx.errors.SphinxWarning: /Users/willjones/Documents/code_projects/delta-rs/python/reproduce/bug.py:docstring of bug.write_deltalake::py:class reference target not found: 'error'

Warning, treated as error:
/Users/willjones/Documents/code_projects/delta-rs/python/reproduce/bug.py:docstring of bug.write_deltalake::py:class reference target not found: 'error'