docs: update docstrings to resolve sphinx failures #1030
Merged
Conversation
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
Fixes python-semantic-release#1029 - set `ignore-module-all` for `autodoc_default_options` to resolve some Sphinx errors about duplicate / ambiguous references sphinx-doc/sphinx#4961 (comment) - Standardize some non-standard (Google-ish) docstrings to Sphinx format, to avoid ruff and Sphinx arguing about underline length. - Fix indents and other minor whitespace / formatting changes.
codejedi365
approved these changes
Sep 25, 2024
1 task
This was referenced Feb 5, 2025
Closed
Closed
Closed
Closed
1 task
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.
Purpose
ignore-module-allforautodoc_default_optionsto resolve some Sphinx errors about duplicate / ambiguous references more than one target found for cross reference should prefer current file's method over other libraries methods sphinx-doc/sphinx#4961 (comment)Fixes #1029
Rationale
Happy to do this differently, but Sphinx style seemed to match most of what we had in the codebase
Pros:
Cons:
pydocstyletosphinx.How did you test?
Generated locally and spot-checked that at least type inferences etc. seemed to work Ok.
Note: references to errors raised / types from other libraries aren't automagically linked; I assume that's Ok.
How to Verify
Build docs following docs in contributing guidelines, and view in browser