Skip to content

docs: render #771's two unregistered-member helpers in numbers.rst (#780) - #781

Merged
JarryShaw merged 1 commit into
mainfrom
docs/780-numbers-unregistered-member-stubs
Sep 25, 2026
Merged

JarryShaw merged 1 commit into
mainfrom
docs/780-numbers-unregistered-member-stubs

Conversation

@JarryShaw

Copy link
Copy Markdown
Owner

Please follow the guide below

What is the purpose of your pull request?

Tick the commit type your subject line carries.

  • fix — corrects a defect
  • feat — adds a feature
  • perf — changes performance, not behaviour
  • refactor — changes neither behaviour nor performance
  • test — tests only
  • docs — documentation only
  • ci — workflows or build tooling
  • chore — anything else

Description of your pull request and other information

Closes #780.

#771 added _rebuild_unregistered_member and _reduce_unregistered_member to pcapkit/corekit/fields/numbers.py. Both carry full Args:/Returns: docstrings, but numbers.rst listed no stubs for them, so neither was rendered.

  • Stubs — two .. autofunction:: entries under the existing Internal Definitions heading, after the NumberField autoclass (source order). Individual stubs follow the _purge precedent at docs/source/pcapkit/foundation/engines/3rdparty.rst:481; :private-members: stays commented out repo-wide.
  • Prose → :func: — the only two convertible references are both to _rebuild_unregistered_member, at numbers.py:680 (in EnumField._unregistered_member's Note:) and numbers.py:804 (in _reduce_unregistered_member's Returns:). Relative roles, matching _pcap_backend.py:198's ``:func:_purge```. Everything else still in double backticks is an enum/object internal with no stub here (reduce_ex`, `value`, `name`, `new`, `value2member_map`, `missing` — the last is in `conf.py`'s `exclude-members`).

Verification — full sphinx-build -b html -E, Sphinx 9.1.0 / Python 3.14.7, with the resolved package root asserted in-process as this tree (the venv's editable install otherwise wins over cwd). 53 warnings before, 53 after — byte-for-byte identical after sorting, so no new warning and no duplicate object description for either stub. Both stubs render their own id= anchor and Args:/Returns: body; the two prose references resolve to internal links (xref py py-func), with zero plain literals left for that name.

)

* Add `.. autofunction::` stubs for `_rebuild_unregistered_member` and
  `_reduce_unregistered_member` under the existing Internal Definitions
  heading. Both carry full `Args:`/`Returns:` docstrings that went
  unrendered because the file listed no stubs for them. This follows the
  `_purge` precedent in `3rdparty.rst` rather than a blanket
  `:private-members:` toggle, which stays commented out repo-wide.
* Promote the two prose references to `_rebuild_unregistered_member`
  from double backticks to `:func:` roles, now that the stubs make them
  resolve. They were literals deliberately, to avoid a dangling
  cross-reference while the stubs were absent.

Docs build: 53 warnings before, 53 after -- byte-for-byte identical after
sorting. Both stubs render with their own anchors and the two prose
references resolve to internal links.
@JarryShaw JarryShaw added docs Pull requests that change documentation only (docs: subject prefix) review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Sep 25, 2026
@JarryShaw

Copy link
Copy Markdown
Owner Author

Cross-review at e6a50a75c (sonnet, a different model from the author): GOOD TO GO, no required changes.

The claim I could not check cheaply is confirmed, and confirmed the hard way. Both trees built separately with PYTHONPATH forced to each and pcapkit.__file__ printed in-process before the build — /tmp/pr781-main/pcapkit/__init__.py against the head's own worktree, so neither read the shared checkout. sphinx-build -b html -E, Sphinx 9.1.0 / Python 3.14.7: 53 warnings each, and after stripping the two builds' distinct absolute-path prefixes and sorting, diff was empty with matching md5 (67de2ab6…). The three duplicate object description warnings are present identically in both.

The mechanism claim behind that measurement also holds, which matters because it decides whether the warning diff means anything: sys.meta_path in the venv is [DistutilsMetaFinder, BuiltinImporter, FrozenImporter, PathFinder, _EditableFinder] — the editable finder really does sit after PathFinder, so PYTHONPATH wins. Demonstrated both ways: without it, import pcapkit resolves to the shared checkout; with it, to the worktree.

Both stubs render. Own id= anchors, full Args:/Returns:/Return type: bodies, and both :func: roles resolve to internal links — <a class="reference internal"> wrapping <code class="xref py py-func">, with the auto-appended () that only a resolved func-xref gets. The baseline has zero stub anchors and exactly one plain literal with no link, matching the author's "1 literal / 0 links". The relative-role concern I raised is refuted: both resolve, including the one from a method docstring at :680, which was the case I thought might fail silently.

One claim narrower than it reads, not a defect. The author justified placement as "the file follows source order". numbers.rst is actually ordered thematically — Sized, Enumeration, Internal — and NumberField is numbers.py's first class at :35 yet is documented last. The narrow claim does hold: the helpers at :757 and :785 come after :35, and the Sized Fields section is internally source-ordered. Worth knowing the file's real convention.

Also swept: no stub exists anywhere under docs/source/ for any of the twelve names left in double backticks, so none was a missed conversion, and _missing_ is confirmed in conf.py:115's exclude-members where a role could never have resolved. Template intact, one commit, Closes #780.

Eight CI legs still outstanding on this head (19 success, 3 expected skips, 0 failures). This is a review verdict, not a merge signal.

@JarryShaw JarryShaw added review: good-to-go Cross-review at the current head says ready; CI state is separate and removed review: pending No verdict for the current head - never reviewed, or the head moved since the last one labels Sep 25, 2026
@JarryShaw
JarryShaw merged commit 25499d5 into main Sep 25, 2026
31 checks passed
@JarryShaw
JarryShaw deleted the docs/780-numbers-unregistered-member-stubs branch September 25, 2026 13:17
@JarryShaw JarryShaw removed the review: good-to-go Cross-review at the current head says ready; CI state is separate label Sep 25, 2026
@JarryShaw JarryShaw added this to the 1.5 milestone Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Pull requests that change documentation only (docs: subject prefix)

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

docs: numbers.rst has no autofunction stubs for #771's two new unregistered-member helpers

1 participant