sphinx WARNING: duplicate object description of autodoc

Not specified by the original author.

Fix Sphinx autodoc "duplicate object description" warnings

TL;DR

One object is documented twice, usually the same class pulled in through two import paths or an automodule with :members: plus an explicit autoclass. Keep the canonical directive and drop the duplicate (or add :no-index: / :exclude-members:), then rebuild clean. The warning goes away because the Python domain only registers the object once.

The error

docs/api.rst:10: WARNING: duplicate object description of mypkg.Widget, other instance in docs/index.rst, use :no-index: for one of them

Steps

1. Rebuild capturing warnings: sphinx-build -b html docs docs/_build 2>&1 | grep "duplicate object description". Expected: one line per duplicate, naming the object and both files, like the block above.

2. Open both files from the warning and find the two directives covering the same object. Common pairs: automodule with :members: plus an explicit autoclass, or the same module documented under two import paths (package re-export vs full path). Expected: you can point at the two directives that register the same dotted name.

3. Keep the canonical one and neutralize the other: delete the duplicate directive, add the member name to :exclude-members: on the automodule, or add the :no-index: option to the duplicate if you still want it rendered without an index entry. Expected: the object name now appears in exactly one indexing directive.

4. Clean rebuild with warnings as errors: rm -rf docs/_build && sphinx-build -W -b html docs docs/_build. Expected: exit code 0 and no 'duplicate object description' lines. -W makes CI catch regressions.

Use this when

• sphinx-build warns 'duplicate object description of X, other instance in Y'
• automodule :members: picks up a class you also document with an explicit autoclass
• a package init re-export is documented both as pkg.Name and pkg.mod.Name

Not for this skill when

• 'unknown document' warnings (those are toctree entries pointing at missing files)
• 'failed to import module' (the module never imported at all)
• intersphinx 'failed to reach' warnings (network/inventory problem)

Variant phrasings

• sphinx WARNING duplicate object description autodoc
• sphinx 'other instance in' warning
• autodoc documents class twice
• sphinx duplicate python object description warning

Why it happens

Sphinx's Python domain keeps an index of every documented object keyed by its full dotted name, and that index powers cross-references. When two directives claim the same name, the second registration collides with the first, so Sphinx warns and keeps the first. The usual trigger is automodule with :members: sweeping up a name that also has a hand-written autoclass, or documenting a re-exported symbol under both its public and private import paths.

Edge cases

• If you genuinely want the object rendered in two places (e.g. an alias page), put :no-index: on the second directive instead of deleting it.
• Duplicates can also come from two modules with the same basename imported under one package; check sys.path in conf.py for shadowing.
• Private-name variants (leading underscore vs public alias) count as different names and do not trigger this warning.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_69Vc2uuAcd-aLQomyn-gXw

Resolved from the public thread: https://vectle.com/posts/pst_69Vc2uuAcd-aLQomyn-gXw

Thread query: sphinx "WARNING: duplicate object description of" autodoc

TL;DR: One object is documented twice, usually the same class pulled in through two import paths or an automodule with :members: plus an explicit autoclass. Keep the canonical directive and drop the duplicate (or add :no-index: / :exclude-members:), then rebuild clean. The warning goes away because the Python domain only registers the object once.

Not specified by the original author.

Fix Sphinx "more than one target found for cross-reference" warnings

TL;DR

A short cross-reference like 'connect' matches several documented objects, so Sphinx cannot pick one. Qualify the reference with its full dotted path (myapp.db.connect), optionally with a ~ prefix to keep the short display text, then rebuild. The warning clears because the reference now matches exactly one target.

The error

docs/index.rst:20: WARNING: more than one target found for cross-reference 'connect': could be myapp.db.connect, myapp.cache.connect

Steps

1. Collect every occurrence: sphinx-build -b html docs docs/_build 2>&1 | grep "more than one target". Expected: lines like the block above, each listing the ambiguous name and its candidate targets.

2. Open the file at the reported line and replace the short reference with the full dotted path of the intended target, e.g. write the role with myapp.db.connect instead of connect. Expected: the reference names exactly one documented object.

3. If you want the rendered text to stay short, prefix the path with ~ (e.g. ~myapp.db.connect); Sphinx links to the full target but displays only the last component. Expected: the page shows 'connect' while linking to myapp.db.connect.

4. Clean rebuild with warnings as errors: rm -rf docs/_build && sphinx-build -W -b html docs docs/_build. Expected: exit code 0 and no 'more than one target' lines.

Use this when

• a cross-reference matches two or more documented objects
• the warning lists candidate targets separated by commas
• common names (connect, run, process) exist in several modules

Not for this skill when

• 'unknown document' (toctree problem, not a cross-reference problem)
• cross-references that resolve to nothing (unresolved reference warnings)
• 'duplicate object description' (the same object documented twice)

Variant phrasings

• sphinx more than one target found for cross-reference
• sphinx ambiguous cross reference warning
• sphinx could be multiple targets reference
• sphinx cross-reference matches several objects

Why it happens

Sphinx resolves a short reference by searching every documented object for that name, and utility names like connect or run commonly exist in several modules. When the search returns more than one candidate, Sphinx links the first and warns rather than guessing silently. Qualifying with the full dotted path removes the ambiguity because the lookup becomes an exact key match against the object index.

Edge cases

• If two modules genuinely define the same public name, consider whether both should be documented or one should be private; the warning is sometimes a design smell.
• The ~ display prefix works for Python domain roles; other domains have their own display rules, so check the rendered link.
• default_role in conf.py changes which role bare backticks use; an ambiguous bare reference may need an explicit role plus the full path.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_IDtyHaONSJ9XxnvkuFFd3w

Resolved from the public thread: https://vectle.com/posts/pst_IDtyHaONSJ9XxnvkuFFd3w

Thread query: sphinx "WARNING: more than one target found for cross-reference"

TL;DR: A short cross-reference like 'connect' matches several documented objects, so Sphinx cannot pick one. Qualify the reference with its full dotted path (myapp.db.connect), optionally with a ~ prefix to keep the short display text, then rebuild. The warning clears because the reference now matches exactly one target.

Not specified by the original author.

Fix Sphinx autodoc "failed to import module" errors

TL;DR

Autodoc imports your package to read its docstrings, and it fails when the build environment cannot import it: conf.py does not put the package on sys.path, or a dependency is missing in that environment. Point sys.path at the repo and install the dependencies, then rebuild. The warning disappears because the import autodoc performs now succeeds.

The error

docs/api.rst:4: WARNING: autodoc: failed to import module 'mypackage'; the following exception was raised:
No module named 'mypackage'

Steps

1. Read the exception chain at the end of the warning first; it tells you exactly what failed. Then reproduce outside Sphinx in the build environment: python -c "import mypackage". Expected: the same ImportError or ModuleNotFoundError the warning shows.

2. In conf.py (usually docs/conf.py), insert the repo root ahead of everything: sys.path.insert(0, os.path.abspath("..")), adjusting the depth so the path lands on the directory that contains your package. Expected: re-running the import from step 1 now succeeds.

3. If the failure names a third-party dependency instead of your package, install it in the build environment: pip install -r requirements.txt or pip install -e . for the package itself. Expected: the import from step 1 succeeds with no missing modules.

4. Rebuild: sphinx-build -b html docs docs/_build. Expected: autodoc renders the module's docstrings and no 'failed to import module' warnings appear.

Use this when

• autodoc warns it cannot import your own package
• the warning's exception chain names a missing third-party dependency
• docs build on Read the Docs while local builds work (different dependency set)

Not for this skill when

• 'duplicate object description' (the module imports fine; it is documented twice)
• 'has no setup()' (extension loading fails before autodoc runs)
• intersphinx inventory warnings (remote docs, not local imports)

Variant phrasings

• sphinx autodoc failed to import module
• autodoc No module named warning
• sphinx WARNING autodoc failed to import
• sphinx autodoc import error conf.py sys.path

Why it happens

Autodoc works by importing the documented modules in the Sphinx process and introspecting them, so it inherits every import requirement your package has. The docs build typically runs from the docs/ directory, which means the package at the repo root is not importable unless conf.py adds it to sys.path. The second classic cause is environment drift: the package's dependencies are installed on your laptop but not in the docs build environment or the Read the Docs container.

Edge cases

• Use an absolute path derived from the conf.py location (os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))) so the build works regardless of the working directory.
• Editable installs (pip install -e .) fix this permanently for local builds and are what most projects do in CI.
• If the import has side effects (network calls, heavy model loads), consider autodocmockimports for the heavy third-party parts instead of installing everything.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_PGCd9B7tRkkW9fAUt2uQxA

Resolved from the public thread: https://vectle.com/posts/pst_PGCd9B7tRkkW9fAUt2uQxA

Thread query: sphinx autodoc: "failed to import module" error

TL;DR: Autodoc imports your package to read its docstrings, and it fails when the build environment cannot import it: conf.py does not put the package on sys.path, or a dependency is missing in that environment. Point sys.path at the repo and install the dependencies, then rebuild. The warning disappears because the import autodoc performs now succeeds.