Skip to content

fix(docs): document KeyOverlay id/name once, on the properties - #53

Merged
CSSFrancis merged 1 commit into
mainfrom
fix/keys-duplicate-object-desc
Aug 2, 2026
Merged

fix(docs): document KeyOverlay id/name once, on the properties#53
CSSFrancis merged 1 commit into
mainfrom
fix/keys-duplicate-object-desc

Conversation

@CSSFrancis

Copy link
Copy Markdown
Owner

The bug

The docs build has been red on every commit since the keys work landed in v0.7.0322029eb was the last green run. It is not specific to any PR; main itself fails at 78b6819e.

KeyOverlay.id and .name are documented twice: once in the class docstring's Attributes block, and again as bare @property definitions that autoclass :members: in docs/api/keys.rst picks up. Sphinx reports each as a duplicate object description, and docs.yml builds with -W:

<unknown>:1: WARNING: duplicate object description of anyplotlib.keys.KeyOverlay.id, other instance in api/keys, use :no-index: for one of them
<unknown>:1: WARNING: duplicate object description of anyplotlib.keys.KeyOverlay.name, other instance in api/keys, use :no-index: for one of them
build finished with problems, 2 warnings (with warnings treated as errors)

Because Deploy docs is gated on needs: build, the published docs have not updated since v0.7.0 either.

The fix

Move the two descriptions onto the properties and drop the Attributes block.

The warning message itself suggests :no-index:, but that just suppresses one of two copies that would still have to be kept in sync by hand. The properties had no docstrings at all, so putting the text there is where it belonged: one copy, at the definition, and the rendered page is unchanged — both descriptions still appear under id and name in the API reference (verified in the built HTML).

Verification

  • Full sphinx-build -b html docs build/html -W --keep-going (the exact CI invocation, with the Pyodide wheel staged first): build succeeded, zero warnings, versus 2 before the change on the same tree.
  • test_keys + test_documentation: 68 passed.

Independent of #52; either can merge first.

The docs build has failed on every commit since the keys work landed
(v0.7.0): `KeyOverlay.id` and `.name` were described in the class
docstring's `Attributes` block AND defined as bare properties that
`autoclass :members:` documents too, so Sphinx emitted

    duplicate object description of anyplotlib.keys.KeyOverlay.id,
    other instance in api/keys, use :no-index: for one of them

and the build runs with `-W`.

Move the two descriptions onto the properties rather than silencing the
warning with `:no-index:`. A property's docstring is where its docs
belong, the text is unchanged and still renders, and there is no second
copy left to drift out of sync.

Full `sphinx-build -b html docs build/html -W --keep-going` now succeeds
with zero warnings.
@codecov-commenter

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.77%. Comparing base (78b6819) to head (4cd3c68).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main      #53   +/-   ##
=======================================
  Coverage   90.77%   90.77%           
=======================================
  Files          40       40           
  Lines        4500     4500           
=======================================
  Hits         4085     4085           
  Misses        415      415           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@CSSFrancis
CSSFrancis merged commit 6cf8719 into main Aug 2, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants