Repository navigation
docs: link bare pcap module mentions to the PyPCAP/pcap-ct note (#1948) - #1952
Conversation
- Label the note in engines/3rdparty.rst that explains both distributions install the same top-level pcap module, as pcap-module. - Define |pcap|_ in rst_epilog with that label's anchor as its target, and add a doctree-resolved hook, link_pcap_module, that points it at the note's page from every other page, so it renders as a linked literal like |pkg|_. - Write the rendered module mentions in docs pages and engine docstrings as |pcap|_; keep distribution names, code, engine and adapter names, the file format, and the note itself as literals. - Make index.rst's PCAP file-format link anonymous, since target names fold case and its named target clashed with the epilog's pcap target. - Pin the label, the epilog entry, the hook and the bare-literal scan in test_docs_pcap_module_link_1948_unit.py, and let the #1936 guard accept the internal target. Closes #1948
- link_pcap_module leaves the bare anchor alone when the builder's URI for the note's page is itself a fragment, as singlehtml's is, instead of writing a second '#' into it. - It replaces each link with its literal when the builder raises NoUri for the note's page, as latex does when its document set leaves the note out, instead of failing the build. - Build a scratch project under singlehtml and latex in the #1948 test, so the hook is exercised by real builders rather than a mock. Closes #1948
|
NEEDS CHANGES at |
- Restate the latex builder test's docstring as what it pins: latex has no URI for a page outside its document set, so each link is written as its literal. - Word the KEPT allowlist comment without "still". Closes #1948
|
GOOD TO GO at |
make pylint,make mypy,make isort)make testpasses, and a test case covers the changeWhat is the purpose of your pull request?
docs— documentation onlyDescription of your pull request and other information
Links each rendered bare
pcapmodule mention to the note explaining that PyPCAP and pcap-ct both install that module (#1948, option 1). The note inengines/3rdparty.rstgets apcap-modulelabel, and|pcap|_inrst_epilogtargets it.An epilog target cannot reach a label on another page: an indirect target fails off its own page, and
:ref:renders plain text rather than a literal. So adoctree-resolvedhandler inconf.py,link_pcap_module, points the link at the note's page from every other page, and warns if the label is missing.index.rst'sPCAPWikipedia link becomes anonymous, because target names fold case and its named target clashed withpcap. Code, distribution names, engine names and the file format stay literal.The hook leaves singlehtml's single-page anchor alone and writes the plain literal where a builder has no page for the note (latex without it).
tests/project/test_docs_pcap_module_link_1948_unit.py, including real singlehtml and latex builds, fails without the change. The docs build on the pinned versions has no warnings.Closes #1948