Fix malformed-RST docstring warnings and enable -W in CI#118
Open
levon003 wants to merge 2 commits into
Open
Conversation
Clears all Sphinx build warnings so the docs build can be gated with -W: - Suppress peewee back-reference accessors (e.g. `Dataset.messages`) in skip_peewee_internals. Like the already-filtered DoesNotExist/`_id` members they're peewee-generated, render as bare names with no docstring or type, and tripped 18 docutils warnings. - Fix malformed RST in docstrings (JsonView, MetricComputer.compute_metrics, the completion_functions module, count_errors, process_conversation, process_single_message): code/dict blocks now use `::` literal blocks, bullet lists get blank lines, `*_errors` is escaped, and the two over-indented Google-style docstrings are reflowed. - Coerce instead of warn when autodoc-pydantic can't build a JSON schema for a field (FunctionsCollection.functions is a list[Callable], which has no schema representation by design). - Build docs with `-W --keep-going` in the validate.yaml docs job so warnings fail the build and can't silently accumulate. Addresses items 3, 4, and 6 of #117. Verified: `make html SPHINXOPTS="-W --keep-going"` exits clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Patch release: docstring fixes (which ship in the package) plus docs-build hygiene. No API or behavior changes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.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
1 participant
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.
Addresses items 3, 4, and 6 of #117, getting the docs build to zero warnings so it can be gated with
-W.What changed
docs/conf.py).Dataset.messages,EvalSetRun.metrics_list, the m2m*_links, etc. are peewee-generated reverse relations that render as bare names with no docstring or type — and they accounted for 18 of the docutils warnings. They're now filtered inskip_peewee_internals, consistent with the already-suppressedDoesNotExistand<fk>_idmembers.JsonView,MetricComputer.compute_metrics, thecompletion_functionsmodule docstring,count_errors,process_conversation, andprocess_single_message. Dict/code blocks now use::literal blocks, bullet lists get surrounding blank lines,*_errorsis escaped to avoid a stray-emphasis warning, and the two over-indented Google-style docstrings are reflowed. (process_single_messagesurfaced as a docutils ERROR only once-Wwas on.)FunctionsCollection.functionsis alist[Callable], which has no JSON-schema representation by design, soautodoc_pydantic_model_show_json_error_strategy = "coerce"renders the serializable fields instead of warning.-W --keep-goingin thevalidate.yamldocs job (item 4) so doc warnings fail PRs instead of silently accumulating.Verification
make html SPHINXOPTS="-W --keep-going"exits 0 (was: 35 warnings onmainbefore the #86 work; this brings it to zero). Spot-checked that the fixed docstrings render as proper highlighted code blocks, not mangled text.Remaining in #117
Items 1 (dead
linkcode_resolve), 2 (no-opdocutils_conf), 5 (redundantnapoleon/numpydoc+ unused matplotlib extensions), and 7 (optionalmake linkcheck).🤖 Generated with Claude Code