sphinx "WARNING: duplicate object description of" autodoc

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