Fix warnings in building of documentation #226
Merged
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 rendered version of this PR can be found here.
Status quo
When running
make html
indatajudge/docs
onmain
, 178 warnings are produced withsphinx
7.3.7.Few of those warnings are indeed desired in that they hint at problems we'd want to fix, e.g. :
Yet, the bulk of the warnings is of one of two forms:
/Users/kevinklein/Code/datajudge/src/datajudge/requirements.py:docstring of datajudge.requirements.Requirement:19: WARNING: autosummary: stub file not found 'datajudge.Requirement.append'. Check your autosummary_generate setting.
/Users/kevinklein/Code/datajudge/src/datajudge/requirements.py:docstring of datajudge.requirements.Requirement.insert:21: WARNING: Explicit markup ends without a blank line; unexpected unindent.
Proposed changes
autosummary: stub file not found 'datajudge.Requirement.append'. Check your autosummary_generate setting.
warnings are eliminated by inheriting doc strings for non-overwritten methods from parent classes.Explicit markup ends without a blank line; unexpected unindent.
warnings are eliminated for a reason that's clear to me.Running
make html
on this branch creates no more warnings.Remarks
In order to address the
Explicit markup ends without a blank line; unexpected unindent.
warnings, I tried adaptations of the doc strings suggested in this stackoverflow thread. Unfortunately it didn't resolve the issue at hand.