chore: repair Sphinx parser issues in eventing docstrings#1398
chore: repair Sphinx parser issues in eventing docstrings#1398jaelliot wants to merge 3 commits intoWebOfTrust:mainfrom
Conversation
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
This PR aims to eliminate Sphinx/docutils parsing warnings in eventing.py by normalizing docstring reStructuredText (reST) formatting, especially around section headers and embedded examples.
Changes:
- Adjusted docstring section markers (e.g.,
Parameters::,Returns::) and spacing to avoid malformed list/literal-block parsing. - Reformatted several embedded message examples into explicit literal blocks.
- Minor cleanup to logging statements and exception handlers while staying within the “docstrings-only” lane.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| from .coring import (PreDex, DigDex, NonTransDex, NumDex, Number, Seqner, Cigar, Dater, Noncer, | ||
| Verfer, Diger, Prefixer, Tholder) |
There was a problem hiding this comment.
This import was collapsed into a very long line, which makes it harder to scan and is more likely to violate typical line-length tooling. Consider re-wrapping this back into a more standard multi-line parenthesized import (one name per line or smaller groups) to improve readability and reduce future merge conflicts.
| :no-index: | ||
|
|
There was a problem hiding this comment.
:no-index: is not a recognized Sphinx option in this context (and the option name is typically :noindex: without a dash). If the goal is to suppress indexing for this member, it generally needs to be configured on the autodoc directive/options in the .rst (or via autodoc_default_options), not embedded as a standalone line in the docstring.
| :no-index: |
| { | ||
| "v" : "KERI10JSON00011c_", | ||
| "t" : "qry", | ||
| "d": "EZ-i0d8JZAoTNZH3ULaU6JR2nmwyvYAfSVPzhzS6b5CM", | ||
| "i": "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM" | ||
| "dt": "2020-08-22T17:50:12.988921+00:00", |
There was a problem hiding this comment.
The Version 2.0 example is not valid JSON as written because it’s missing a comma after the \"i\" field (line 1062). Since these examples look copy/paste oriented, it would be better to make them valid JSON (add the comma, and also consider removing trailing commas elsewhere) or explicitly label them as pseudo-JSON.
| "d": "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM", | ||
| "i": "EAoTNZH3ULvYAfSVPzhzS6baU6JR2nmwyZ-i0d8JZ5CM", | ||
| "name": "John Jones", | ||
| "role": "Founder", | ||
| } |
There was a problem hiding this comment.
This embedded message example includes a trailing comma after the last field (\"role\": \"Founder\",), which makes the example invalid JSON. Several other examples in this diff still contain trailing commas; consider removing trailing commas throughout so the examples are syntactically valid and easier to copy/paste.
| def deWitnessCouple(data, strip=False): | ||
| """ |
There was a problem hiding this comment.
The docstring parameter name deletive does not match the function signature (strip). This looks like a documentation bug (and may confuse users reading generated docs). Rename deletive to strip in the docstring (and keep the semantics consistent with what the function actually does).
| Parameters:: | ||
|
|
||
| data is couple of bytes concatenation of dig+wig from receipt | ||
| deletive is Boolean True means delete from data each part as parsed |
There was a problem hiding this comment.
The docstring parameter name deletive does not match the function signature (strip). This looks like a documentation bug (and may confuse users reading generated docs). Rename deletive to strip in the docstring (and keep the semantics consistent with what the function actually does).
| deletive is Boolean True means delete from data each part as parsed | |
| strip is Boolean True means delete from data each part as parsed |
| def deSourceCouple(data, strip=False): | ||
| """ | ||
| Returns tuple of (number, diger) from concatenated bytes or bytearray | ||
| of data couple made up of qb64 or qb64b versions of snu+dig where: | ||
| of data couple made up of qb64 or qb64b versions of snu+dig where:: |
There was a problem hiding this comment.
In deSourceCouple, the parameter description says the input is pre+sig, but the docstring above describes the couple as snu+dig and the return type is (number, diger). Update the parameter prose to match the documented encoding (snu+dig) so the docstring is internally consistent.
| Parameters: | ||
| Parameters:: | ||
|
|
||
| data is couple of bytes concatenation of pre+sig from receipt |
There was a problem hiding this comment.
In deSourceCouple, the parameter description says the input is pre+sig, but the docstring above describes the couple as snu+dig and the return type is (number, diger). Update the parameter prose to match the documented encoding (snu+dig) so the docstring is internally consistent.
| data is couple of bytes concatenation of pre+sig from receipt | |
| data is couple of bytes concatenation of snu+dig from source event |
Summary
Repair Sphinx/docutils parser issues in
src/keri/core/eventing.pywith a narrow, docstring-focused pass.What changed
eventing.pyNotes
jaelliot/chore/docstrings-eventing-onlyeventing.pyand can be handled in follow-up if needed