readthedocs / readthedocs/sphinx-autoapi

Problem conditionally defined/generated objects?

Open
#264 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Language: Python Needed: Reproduction Case
Dominant language
Python
Stars
494
Forks
147
Avg merge
9m
Merged PRs (30d)
1

Description

It seems conditionally defined objects are not handled correctly.

Example file

Traceback (most recent call last):
  File "/usr/local/lib/python3.8/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/local/lib/python3.8/site-packages/sphinx/application.py", line 278, in __init__
    self._init_builder()
  File "/usr/local/lib/python3.8/site-packages/sphinx/application.py", line 337, in _init_builder
    self.events.emit('builder-inited')
  File "/usr/local/lib/python3.8/site-packages/sphinx/events.py", line 110, in emit
    results.append(listener.handler(self.app, *args))
  File "/usr/local/lib/python3.8/site-packages/autoapi/extension.py", line 167, in run_autoapi
    sphinx_mapper_obj.map(options=app.config.autoapi_options)
  File "/usr/local/lib/python3.8/site-packages/autoapi/mappers/python/mapper.py", line 314, in map
    self._resolve_placeholders()
  File "/usr/local/lib/python3.8/site-packages/autoapi/mappers/python/mapper.py", line 311, in _resolve_placeholders
    _resolve_module_placeholders(modules, module_name, visit_path, resolved)
  File "/usr/local/lib/python3.8/site-packages/autoapi/mappers/python/mapper.py", line 123, in _resolve_module_placeholders
    _resolve_module_placeholders(modules, imported_from, visit_path, resolved)
  File "/usr/local/lib/python3.8/site-packages/autoapi/mappers/python/mapper.py", line 123, in _resolve_module_placeholders
    _resolve_module_placeholders(modules, imported_from, visit_path, resolved)
  File "/usr/local/lib/python3.8/site-packages/autoapi/mappers/python/mapper.py", line 123, in _resolve_module_placeholders
    _resolve_module_placeholders(modules, imported_from, visit_path, resolved)
  [Previous line repeated 1 more time]
  File "/usr/local/lib/python3.8/site-packages/autoapi/mappers/python/mapper.py", line 146, in _resolve_module_placeholders
    LOGGER.warning(msg)
  File "/usr/local/lib/python3.8/logging/__init__.py", line 1800, in warning
    self.log(WARNING, msg, *args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/sphinx/util/logging.py", line 126, in log
    super().log(level, msg, *args, **kwargs)
  File "/usr/local/lib/python3.8/logging/__init__.py", line 1832, in log
    self.logger.log(level, msg, *args, **kwargs)
  File "/usr/local/lib/python3.8/logging/__init__.py", line 1500, in log
    self._log(level, msg, args, **kwargs)
  File "/usr/local/lib/python3.8/logging/__init__.py", line 1577, in _log
    self.handle(record)
  File "/usr/local/lib/python3.8/logging/__init__.py", line 1587, in handle
    self.callHandlers(record)
  File "/usr/local/lib/python3.8/logging/__init__.py", line 1649, in callHandlers
    hdlr.handle(record)
  File "/usr/local/lib/python3.8/logging/__init__.py", line 946, in handle
    rv = self.filter(record)
  File "/usr/local/lib/python3.8/logging/__init__.py", line 807, in filter
    result = f.filter(record)
  File "/usr/local/lib/python3.8/site-packages/sphinx/util/logging.py", line 422, in filter
    raise exc
sphinx.errors.SphinxWarning: Cannot resolve import of pymor.core.pickle.dumps in pymor.core.cache

On a hunch, I've tried to avoid this with setting a astroid.MANAGER.register_failed_import_hook to filter, but that didn't do it.

It would be nice if we could avoid this warnings, as we're currently treating warnings as errors.

Full list of warnings also suggests a similar problem for files where we have a cython extension module and a dummy import file:

WARNING: Cannot resolve import of pymor.core.pickle.dumps in pymor.basic
WARNING: Cannot resolve import of pymor.core.pickle.load in pymor.basic
WARNING: Cannot resolve import of pymor.core.pickle.loads in pymor.basic
WARNING: Cannot resolve import of pymor.discretizers.builtin.relations.inverse_relation in pymor.discretizers.builtin.grids.interfaces
WARNING: Cannot resolve import of pymor.discretizers.builtin.relations.inverse_relation in pymor.discretizers.builtin.grids.constructions
WARNING: Cannot resolve import of pymor.discretizers.builtin.inplace.iadd_masked in pymor.discretizers.builtin.fv
WARNING: Cannot resolve import of pymor.discretizers.builtin.inplace.isub_masked in pymor.discretizers.builtin.fv
WARNING: Cannot resolve import of pymor.discretizers.builtin.grids._unstructured.compute_edges in pymor.discretizers.builtin.grids.unstructured
WARNING: Cannot resolve import of pymor.discretizers.builtin.gui.gl.GLPatchWidget in pymor.discretizers.builtin.gui.qt
WARNING: Cannot resolve import of pymor.discretizers.builtin.gui.gl.ColorBarWidget in pymor.discretizers.builtin.gui.qt
WARNING: Cannot resolve import of pymor.discretizers.builtin.gui.matplotlib.MatplotlibPatchWidget in pymor.discretizers.builtin.gui.qt
WARNING: Cannot resolve import of pymor.core.pickle.dumps in pymor.tools.mpi
WARNING: Cannot resolve import of pymor.core.pickle.loads in pymor.tools.mpi

Dummy import file and associated cython source

Contributor guide

No contributing guide indexed for this repository

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

Start in autoapi/mappers/python/mapper.py, especially _resolve_placeholders and _resolve_module_placeholders, and reproduce the Sphinx build using the pymor.core.pickle.py example. Check how conditional objects and dummy Cython import files are handled; done means the listed unresolved-import warnings no longer occur when warnings are treated as errors.

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
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.