Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wjones127 opened this issue May 31, 2022 · 3 comments
Closed

Comments

@wjones127
Copy link

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
Copy link
Author

Might be identical to: #9775

@AA-Turner
Copy link
Member

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
Copy link
Author

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'

@AA-Turner AA-Turner added this to the 5.0.2 milestone Jun 5, 2022
@tk0miya tk0miya closed this as completed Jun 6, 2022
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 7, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

3 participants