Use docrep to deduplicate shared parameter docstrings#55
Draft
endolith wants to merge 2 commits into
Draft
Conversation
Use docrep (per discussion in issue #6) so repeated Parameters text for utilities and for election generator size/RNG options lives in one place. Introduce elsim._docstrings with a shared DocstringProcessor and anchor stubs; elections reuses n_voters/n_cands/random_state via substitutions and keep_params slices for normal_electorate. Co-authored-by: endolith <endolith@gmail.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #55 +/- ##
==========================================
+ Coverage 96.31% 96.49% +0.17%
==========================================
Files 19 20 +1
Lines 489 513 +24
==========================================
+ Hits 471 495 +24
Misses 18 18
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Codecov flagged the pass lines in _utilities_2d_param_doc and _election_common_param_doc as never executed; call them from tests and assert expanded docstrings contain expected parameter names. Co-authored-by: endolith <endolith@gmail.com>
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.
Summary
Issue #6 suggested using docrep so repeated NumPy-style parameter descriptions are maintained in one place.
This change adds a small
docrepdependency and a sharedDocstringProcessorinelsim/_docstrings.py, then replaces the duplicated blocks for:utilities— the samearray_like/ 2D utilities wording is reused instrategies(honest_rankings,honest_normed_scores,approval_optimal,vote_for_k) andutility_winner.n_voters/n_cands/random_state— shared acrossrandom_utilities,impartial_culture, andnormal_electorate(the latter useskeep_paramsslices sodims/corr/dispstay in the middle).Runtime behavior is unchanged; only
__doc__is assembled at import time. All tests and doctests pass (218 passed).tests/test_docstrings.pyinvokes the doc-anchor stub functions so every line of the new anchor code is covered under Codecov, and checks that docrep expanded__doc__strings include the expected parameter names.Tradeoffs
sixonly) and supports Python ≥3.6 per project metadata.%(election_common.parameters)s); contributors need to know the docrep pattern for new reuse.