docs(corekit): add the sentinels API page so conventions.rst references resolve (#934) - #936
Conversation
JarryShaw
added
docs
JarryShaw
added
review: needs-changes
|
NEEDS CHANGES at
It matters because Everything else confirmed, two of them better than claimed:
Not widening it to the three shim |
…es resolve (#934) - Added docs/source/pcapkit/corekit/sentinels.rst for pcapkit.corekit.sentinels, which had no page, so the five :mod:`pcapkit.corekit.sentinels` references in conventions.rst (lines 165, 168, 171, 174, 261) rendered as plain text. Documents NullType/NULL, NoValueType/NoValue and NoDefaultType/NO_DEFAULT, matching module.rst/enum.rst/field.rst's style for the same three sentinels at their old re-export locations. _Absent/_AbsentType stay off the page: private, absent from __all__, never documented at their pre-#911 home in protocol.rst either. #911 moved all four definitions here, not three -- the page's own prose now says so. - Wired the page into corekit/index.rst's toctree, alphabetically between protochain and version, so it is not an orphan page. - Added tests/project/test_sentinels_doc_page_934_unit.py, pinning the page's existence, its module directive (module:: or automodule::) and its toctree registration; proven to fail (2 failures, 1 error) on main. Verified against a nitpicky sphinx-build: all five conventions.rst references now render real hrefs (were bare <code>); four more pre-existing pcapkit.corekit.sentinels :mod: misses resolve too. Unclaimed bonus: three :class:`~pcapkit.corekit.sentinels.NullType` references (lines 216, 265, 282) used to silently resolve to the wrong page (module.html) with no warning; now correct. Total warnings move 1275 -> 1287 -- pure noise, confirmed: ~21 pre-existing broken internal refs inside NullType/NoDefaultType's own docstrings now fire twice (duplicate-object-description and ambiguous-target counts unchanged, 7 and 36, in both builds). sentinels.py itself stays out of scope.
a8b2cd3 to
99fbfb2
Compare
JarryShaw
added
review: good-to-go
|
GOOD TO GO at The three/four error is fixed, and I verified the delta from the reviewed head
Line Everything substantive was confirmed at The +12 warning rise stands as measured noise, not ambiguity: Still the most valuable thing in this PR and now stated in its body: on One commit, author |
JarryShaw
removed
the
review: good-to-go
…#934) Part B of #934: the remaining nitpicky sphinx-build misses in conventions.rst that are neither the sentinels module refs part A (#936) fixed nor the six aenum roles part C already ruled on (plain literals, since aenum's objects.inv carries zero py: objects and conf.py excludes it deliberately). * Qualified the three unqualified sentinel refs -- :class:`AbsentType`, :class:`NoValueType` and :data:`ABSENT` -- to their real dotted path under pcapkit.corekit.sentinels, so they resolve against the page #936 added. Rewrapped the two lines that grew past this file's ~88-column convention; no wording changed. * Added an autoclass entry for FEATCode to docs/source/pcapkit/const/ftp.rst, and widened the FTP Command section's intro clause to name both classes it now documents -- FEATCode is a companion of Command's, not a peer listed in the page's own overview table, so it stays folded into that section rather than getting its own heading; every other section in this file pairs one heading with one autoclass, and inventing a repeated `.. module::` for a second heading on the same submodule would be a novel shape this file has nowhere else. * Demoted Method.get and part C's six aenum roles to plain double-backtick literals: Method.get carries `:meta private:` deliberately (same pattern as Command.get, OptionType's and AppType's private get overrides), and aenum cannot be cross-referenced at all, so no target can exist for either. * Rebasing onto #940 (merged after this branch started) surfaced a seventh broken reference: #940 deleted FastBindingAcknowledgmentStatus.get outright rather than just widening it, so the :meth: role citing it in the #923 retrospective joined the unresolved set. Demoted to a plain literal too, matching the two sibling examples already written that way in the same sentence (TransportProtocol.get, Criticality.get). * Added test_ftp_featcode_doc_page_934_unit.py, pinning the new autoclass entry the way test_sentinels_doc_page_934_unit.py pins part A's page; proven to fail against the pre-fix (83c7552) page. * Added AenumRoleExclusionTests to test_conventions_doc_claims.py: pins that no :mod:/:class:/etc. role names aenum on this page (the plain-literal demotion is settled policy per conf.py, and nothing else enforced it), and that the four qualified sentinel targets stay qualified. Both assertions proven to fail against the pre-fix (83c7552) page. Nitpicky sphinx-build: conventions.rst had 14 unresolved references against 83c7552, 15 against b337cdb (this branch's rebased base) once #940's deletion is counted; all resolve here. Three more resolve as a side effect of documenting FEATCode: stale FEATCode references inside Command._unregistered_member's and Method._unregistered_member's own docstrings, plus one in a rendered `feat: Optional[FEATCode]` parameter annotation with no clear file attribution. Two pre-existing bugs inside FEATCode's own docstring are newly exposed rather than introduced -- a line-wrapped :meth: role and a reference to the vendor Command.process, deliberately excluded from vendor/ftp.rst's own :members: allowlist. FEATCode's :show-inheritance: does genuinely introduce one new warning of its own (an aenum._enum.StrEnum base that cannot resolve), joining five identical ones already present for Command/Method/etc. Recording rather than fixing any of these: out of scope for this file. mypy 321 errors/38 files, pylint 8.67/10 exit 30, isort clean -- all matching the b337cdb baseline (R0401 cyclic-import churn aside, which is non-deterministic on an unmodified tree). Targeted tests: 40 passed, 1 skipped across test_conventions_doc_claims (incl. the two new AenumRoleExclusionTests methods), test_sentinel_exports_unit, test_sentinels_doc_page_934_unit and the FEATCode page test.
1 participant
make pylint,make mypy,make isort)make testpasses, and a test case covers the changedocs/source/changelog/and regeneratedCHANGELOG.md, if the change is user-visibleN/A -- changelog centralised in #657
What is the purpose of your pull request?
fixfeatperfrefactortestdocscichoreDescription of your pull request and other information
Part of #934:
pcapkit.corekit.sentinelshad no API page, so all five:mod:referencesto it in
conventions.rst(lines 165, 168, 171, 174, 261) rendered as plain text insteadof links. Adds
docs/source/pcapkit/corekit/sentinels.rst, matching the siblingmodule.rst/enum.rst/field.rstpages' style, and wires it intocorekit/index.rst'stoctree so it isn't an orphan.
_Absent/_AbsentTypestay off the page — private, not in__all__, and never documented at their pre-#911 home inprotocol.rsteither. (#911moved all four sentinel definitions into this module, not three; the page's prose says so.)
Verified with a nitpicky
sphinx-build: all five references now render real<a href>anchors (were bare
<code>); four more pre-existingpcapkit.corekit.sentinelsmisseselsewhere resolve too. Unclaimed bonus, caught in cross-review: three
:class:~pcapkit.corekit.sentinels.NullType`` references (conventions.rst:216,265,282)used to silently resolve to the wrong page (`module.html`, the re-export) with no warning
at all — nitpicky mode only catches a miss, not a wrong hit. They now land on this page.
Total warnings move 1275 → 1287 — confirmed noise only:
duplicate object description(7) and
more than one target found(36) counts are unchanged between builds, and neitherfires for any sentinel name. All 21 extra warnings are pre-existing broken internal
docstring refs inside
NullType/NoDefaultType(unqualified__new__, etc.) now firingtwice, once per page documenting the class. Not introduced or fixed here;
sentinels.pyitself is out of scope for this PR.
Added
tests/project/test_sentinels_doc_page_934_unit.py(isort/mypy/pylint clean),proven to fail on
main(2 failures, 1 error), pinning the page's existence, its moduledirective (
module::/automodule::, either resolves the same way), and its toctreeregistration. Ran that file plus
test_sentinel_exports_unit.pyandtest_documentation_claims.py(24 tests, all green) rather than the fullmake test,which OOMs at 29 GB in this environment.