fix(docs): document KeyOverlay id/name once, on the properties - #53
Merged
Conversation
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 Report✅ All modified and coverable lines are covered by tests. 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. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The bug
The docs build has been red on every commit since the keys work landed in v0.7.0 —
322029ebwas the last green run. It is not specific to any PR;mainitself fails at78b6819e.KeyOverlay.idand.nameare documented twice: once in the class docstring'sAttributesblock, and again as bare@propertydefinitions thatautoclass :members:indocs/api/keys.rstpicks up. Sphinx reports each as a duplicate object description, anddocs.ymlbuilds with-W:Because
Deploy docsis gated onneeds: build, the published docs have not updated since v0.7.0 either.The fix
Move the two descriptions onto the properties and drop the
Attributesblock.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 underidandnamein the API reference (verified in the built HTML).Verification
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.