Skip to content

Commit b20fe2f

Browse files
committed
fix(vendor): make wrapped const comments render as written (#1846, #1847)
- Vendor.wrap_comment puts a space after a URL reference that another bracket follows, which docutils autolinked into the next citation, and backslash-escapes a leading reST enumerator such as (S). - Vendor.wrap_comment and AppType.tabulate pass break_on_hyphens=False: a continued line joins with a space, so a hyphen split rendered "run- time" and cut a list-table cell's URL short. - AppType.wrap_comment takes its lines from the base instead of wrapping on its own, so it gets both fixes; nothing it emits trips the #1846 cases yet. - Re-render the affected const comments and AppType tables offline from the committed text, with no crawl. Members, values and code are unchanged. - Add tests/vendor/test_vendor_wrap_comment_unit.py. - Map docutils in tests/_dependency_gates.py, via Sphinx, and record the HAS_DOCUTILS gate as deliberately dark on test and gate. Closes #1846 Closes #1847
1 parent 75a9f23 commit b20fe2f

13 files changed

Lines changed: 330 additions & 65 deletions

File tree

‎pcapkit/const/http/status_code.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,8 +58,8 @@ def __str__(self) -> 'str':
5858
CODE_103 = 103, 'Early Hints'
5959

6060
#: Upload Resumption Supported (TEMPORARY - registered 2024-11-13, extension
61-
#: registered 2025-09-15, expires 2026-11-13) [draft-ietf-httpbis-resumable-
62-
#: upload-05]
61+
#: registered 2025-09-15, expires 2026-11-13)
62+
#: [draft-ietf-httpbis-resumable-upload-05]
6363
CODE_104 = 104, 'Upload Resumption Supported'
6464

6565
#: OK [:rfc:`9110#section-15.3.1`]

‎pcapkit/const/mh/dhcp_support_mode.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ class DHCPSupportMode(EnumRegistry, IntEnum):
2929
#: Unassigned
3030
Unassigned_0x0 = 0x0
3131

32-
#: (S) flag [:rfc:`5844`]
32+
#: \(S) flag [:rfc:`5844`]
3333
S_flag = 0x1
3434

3535
@classmethod

‎pcapkit/const/reg/apptype/apptype.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1391,8 +1391,8 @@ class AppType(EnumRegistry, StrEnum):
13911391
- [N/A] HP Remote Repository for Build and Test Results
13921392
* - ``hpr-toollnx``
13931393
- N/A
1394-
- [N/A] HP Remote System that houses compilers and tools for Linux-
1395-
based Systems
1394+
- [N/A] HP Remote System that houses compilers and tools for
1395+
Linux-based Systems
13961396
* - ``hpr-toolwin``
13971397
- N/A
13981398
- [N/A] HP Remote System that houses compilers and tools for Microsoft
@@ -1909,8 +1909,8 @@ class AppType(EnumRegistry, StrEnum):
19091909
- [N/A] Retrospect backup and restore service
19101910
* - ``rfbc``
19111911
- N/A
1912-
- [N/A] Remote Frame Buffer Client (Used by VNC viewers in listen-
1913-
mode)
1912+
- [N/A] Remote Frame Buffer Client (Used by VNC viewers in
1913+
listen-mode)
19141914
* - ``rfid``
19151915
- N/A
19161916
- [N/A] RFID Reader Mach1(tm) Protocol

‎pcapkit/const/reg/apptype/tcp.py‎

Lines changed: 26 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -76,8 +76,8 @@ class TCP(AppType):
7676
* - ``affinity-cntent``
7777
- [TCP] Affinity content sharing
7878
* - ``ai-adp``
79-
- [TCP] AI Agent Discovery Protocol (ADP) [draft-pro-adp-agent-
80-
discovery-00]
79+
- [TCP] AI Agent Discovery Protocol (ADP)
80+
[draft-pro-adp-agent-discovery-00]
8181
* - ``airdrop``
8282
- [TCP] Airdrop
8383
* - ``airmate``
@@ -151,8 +151,7 @@ class TCP(AppType):
151151
- [TCP] Data transfer service
152152
* - ``boardgame``
153153
- [TCP] Two-player board game play
154-
[https://github.com/chentianren0/MiniXiangqi/blob/main/docs/boardgame-
155-
protocol.md]
154+
[https://github.com/chentianren0/MiniXiangqi/blob/main/docs/boardgame-protocol.md]
156155
* - ``boardplus``
157156
- [TCP] board plus application transfer protocol
158157
* - ``booked-sync``
@@ -209,8 +208,8 @@ class TCP(AppType):
209208
* - ``cerebra``
210209
- [TCP] Control the Cerebra Aquarium Controller
211210
* - ``certificates``
212-
- [TCP] Server for S/MIME and PGP certificates [draft-
213-
bhjl-x509-srv-01]
211+
- [TCP] Server for S/MIME and PGP certificates
212+
[draft-bhjl-x509-srv-01]
214213
* - ``ciao``
215214
- [TCP] Ciao Arduino Protocol
216215
* - ``collabio``
@@ -285,9 +284,9 @@ class TCP(AppType):
285284
"_dots-call-home._tcp" for discovering Call Home DOTS clients used
286285
to establish DOTS signal channel call home. [:rfc:`8973`]; [UDP]
287286
DOTS Signal Channel Call Home Protocol. The service name is used to
288-
construct the SRV service names "_dots-call-home._udp" and "_dots-
289-
call-home._tcp" for discovering Call Home DOTS clients used to
290-
establish DOTS signal channel call home. [:rfc:`8973`]
287+
construct the SRV service names "_dots-call-home._udp" and
288+
"_dots-call-home._tcp" for discovering Call Home DOTS clients used
289+
to establish DOTS signal channel call home. [:rfc:`8973`]
291290
* - ``dots-data``
292291
- [TCP] DOTS Data Channel Protocol. The service name is used to
293292
construct the SRV service name "_dots-data._tcp" for discovering
@@ -727,17 +726,17 @@ class TCP(AppType):
727726
* - ``smartsocket``
728727
- [TCP] home control
729728
* - ``smimeca``
730-
- [TCP] Domain signing certificate for S/MIME keys [draft-
731-
bhjl-x509-srv-01]
729+
- [TCP] Domain signing certificate for S/MIME keys
730+
[draft-bhjl-x509-srv-01]
732731
* - ``snif-cln``
733-
- [TCP] SNIF End-to-End TLS Relay Client Connection [draft-zubov-
734-
snif-05, Section 4.5]
732+
- [TCP] SNIF End-to-End TLS Relay Client Connection
733+
[draft-zubov-snif-05, Section 4.5]
735734
* - ``snif-fifo``
736735
- [TCP] SNIF End-to-End TLS Relay Cluster [draft-zubov-snif-05,
737736
Section 4.6]
738737
* - ``snif-srv``
739-
- [TCP] SNIF End-to-End TLS Relay Service Connection [draft-zubov-
740-
snif-05, Section 4.3]
738+
- [TCP] SNIF End-to-End TLS Relay Service Connection
739+
[draft-zubov-snif-05, Section 4.3]
741740
* - ``soda``
742741
- [TCP] Secure On Device API
743742
* - ``spidap``
@@ -20695,8 +20694,8 @@ class TCP(AppType):
2069520694
#: (Passive Optical Network) systems [TR-352][Inter-Channel-Termination
2069620695
#: protocol (ICTP) is a peer-to-peer protocol with a binary message format that
2069720696
#: is used by a set of optical line terminal (OLT) channel terminations (CT)
20698-
#: comprising a 40-Gigabit-capable next-generation passive optical network (NG-
20699-
#: PON2) system to exchange channel profile configuration and status
20697+
#: comprising a 40-Gigabit-capable next-generation passive optical network
20698+
#: (NG-PON2) system to exchange channel profile configuration and status
2070020699
#: information and to coordinate the operation of tunable optical network units
2070120700
#: (ONUs) in a multi-wavelength channel environment.]
2070220701
pon_ictp = 7202, 'pon-ictp', TransportProtocol.tcp
@@ -23287,8 +23286,8 @@ class TCP(AppType):
2328723286
linogridengine = 12300, 'linogridengine', TransportProtocol.tcp
2328823287

2328923288
#: [TCP] Remote Administration Daemon (RAD) is a system service that offers
23290-
#: secure, remote, programmatic access to Solaris system configuration and run-
23291-
#: time state
23289+
#: secure, remote, programmatic access to Solaris system configuration and
23290+
#: run-time state
2329223291
rads = 12302, 'rads', TransportProtocol.tcp
2329323292

2329423293
#: - [TCP] Warehouse Monitoring Syst SSS
@@ -24487,19 +24486,19 @@ class TCP(AppType):
2448724486
#: - [UDP] GameSmith Port
2448824487
gamesmith_port = 31765, 'gamesmith-port', TransportProtocol.tcp
2448924488

24490-
#: - [TCP] Embedded Device Configuration Protocol TX IANA assigned this well-
24491-
#: formed service name as a replacement for "iceedcp_tx".
24489+
#: - [TCP] Embedded Device Configuration Protocol TX IANA assigned this
24490+
#: well-formed service name as a replacement for "iceedcp_tx".
2449224491
#: - [TCP] Embedded Device Configuration Protocol TX
24493-
#: - [UDP] Embedded Device Configuration Protocol TX IANA assigned this well-
24494-
#: formed service name as a replacement for "iceedcp_tx".
24492+
#: - [UDP] Embedded Device Configuration Protocol TX IANA assigned this
24493+
#: well-formed service name as a replacement for "iceedcp_tx".
2449524494
#: - [UDP] Embedded Device Configuration Protocol TX
2449624495
iceedcp_tx = 31948, 'iceedcp-tx', TransportProtocol.tcp
2449724496

24498-
#: - [TCP] Embedded Device Configuration Protocol RX IANA assigned this well-
24499-
#: formed service name as a replacement for "iceedcp_rx".
24497+
#: - [TCP] Embedded Device Configuration Protocol RX IANA assigned this
24498+
#: well-formed service name as a replacement for "iceedcp_rx".
2450024499
#: - [TCP] Embedded Device Configuration Protocol RX
24501-
#: - [UDP] Embedded Device Configuration Protocol RX IANA assigned this well-
24502-
#: formed service name as a replacement for "iceedcp_rx".
24500+
#: - [UDP] Embedded Device Configuration Protocol RX IANA assigned this
24501+
#: well-formed service name as a replacement for "iceedcp_rx".
2450324502
#: - [UDP] Embedded Device Configuration Protocol RX
2450424503
iceedcp_rx = 31949, 'iceedcp-rx', TransportProtocol.tcp
2450524504

‎pcapkit/const/reg/apptype/udp.py‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -142,9 +142,9 @@ class UDP(AppType):
142142
"_dots-call-home._tcp" for discovering Call Home DOTS clients used
143143
to establish DOTS signal channel call home. [:rfc:`8973`]; [UDP]
144144
DOTS Signal Channel Call Home Protocol. The service name is used to
145-
construct the SRV service names "_dots-call-home._udp" and "_dots-
146-
call-home._tcp" for discovering Call Home DOTS clients used to
147-
establish DOTS signal channel call home. [:rfc:`8973`]
145+
construct the SRV service names "_dots-call-home._udp" and
146+
"_dots-call-home._tcp" for discovering Call Home DOTS clients used
147+
to establish DOTS signal channel call home. [:rfc:`8973`]
148148
* - ``eb-sync``
149149
- [TCP] Easy Books App data sync helper for Mac OS X and iOS; [UDP]
150150
Easy Books App data sync helper for Mac OS X and iOS
@@ -23911,19 +23911,19 @@ class UDP(AppType):
2391123911
#: - [UDP] GameSmith Port
2391223912
gamesmith_port = 31765, 'gamesmith-port', TransportProtocol.udp
2391323913

23914-
#: - [TCP] Embedded Device Configuration Protocol TX IANA assigned this well-
23915-
#: formed service name as a replacement for "iceedcp_tx".
23914+
#: - [TCP] Embedded Device Configuration Protocol TX IANA assigned this
23915+
#: well-formed service name as a replacement for "iceedcp_tx".
2391623916
#: - [TCP] Embedded Device Configuration Protocol TX
23917-
#: - [UDP] Embedded Device Configuration Protocol TX IANA assigned this well-
23918-
#: formed service name as a replacement for "iceedcp_tx".
23917+
#: - [UDP] Embedded Device Configuration Protocol TX IANA assigned this
23918+
#: well-formed service name as a replacement for "iceedcp_tx".
2391923919
#: - [UDP] Embedded Device Configuration Protocol TX
2392023920
iceedcp_tx = 31948, 'iceedcp-tx', TransportProtocol.udp
2392123921

23922-
#: - [TCP] Embedded Device Configuration Protocol RX IANA assigned this well-
23923-
#: formed service name as a replacement for "iceedcp_rx".
23922+
#: - [TCP] Embedded Device Configuration Protocol RX IANA assigned this
23923+
#: well-formed service name as a replacement for "iceedcp_rx".
2392423924
#: - [TCP] Embedded Device Configuration Protocol RX
23925-
#: - [UDP] Embedded Device Configuration Protocol RX IANA assigned this well-
23926-
#: formed service name as a replacement for "iceedcp_rx".
23925+
#: - [UDP] Embedded Device Configuration Protocol RX IANA assigned this
23926+
#: well-formed service name as a replacement for "iceedcp_rx".
2392723927
#: - [UDP] Embedded Device Configuration Protocol RX
2392823928
iceedcp_rx = 31949, 'iceedcp-rx', TransportProtocol.udp
2392923929

‎pcapkit/const/reg/linktype.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -527,12 +527,12 @@ class LinkType(EnumRegistry, IntEnum):
527527
#: [``DLT_NFLOG``] Linux netlink NETLINK NFLOG socket log messages.
528528
NFLOG = 239
529529

530-
#: [``DLT_NETANALYZER``] Ethernet frames with Hilscher netANALYZER pseudo-
531-
#: header.
530+
#: [``DLT_NETANALYZER``] Ethernet frames with Hilscher netANALYZER
531+
#: pseudo-header.
532532
NETANALYZER = 240
533533

534-
#: [``DLT_NETANALYZER_TRANSPARENT``] Ethernet frames with netANALYZER pseudo-
535-
#: header, preamble and SFD, preceded by a Hilscher.
534+
#: [``DLT_NETANALYZER_TRANSPARENT``] Ethernet frames with netANALYZER
535+
#: pseudo-header, preamble and SFD, preceded by a Hilscher.
536536
NETANALYZER_TRANSPARENT = 241
537537

538538
#: [``DLT_IPOIB``] IP-over-InfiniBand.
@@ -544,8 +544,8 @@ class LinkType(EnumRegistry, IntEnum):
544544
#: [``DLT_NG40``] Frames from ng4T GmbH's ng40 protocol tester.
545545
NG40 = 244
546546

547-
#: [``DLT_NFC_LLCP``] NFC Logical Link Control Protocol frames, with a pseudo-
548-
#: header.
547+
#: [``DLT_NFC_LLCP``] NFC Logical Link Control Protocol frames, with a
548+
#: pseudo-header.
549549
NFC_LLCP = 245
550550

551551
#: Packet filter state syncing.
@@ -644,8 +644,8 @@ class LinkType(EnumRegistry, IntEnum):
644644
#: for Bluetooth LE packets.
645645
NORDIC_BLE = 272
646646

647-
#: [``DLT_DOCSIS31_XRA31``] DOCSIS packets and bursts, preceded by a pseudo-
648-
#: header giving metadata about the packet.
647+
#: [``DLT_DOCSIS31_XRA31``] DOCSIS packets and bursts, preceded by a
648+
#: pseudo-header giving metadata about the packet.
649649
DOCSIS31_XRA31 = 273
650650

651651
#: [``DLT_ETHERNET_MPACKET``] IEEE 802.3 mPackets.

‎pcapkit/const/reg/transtype.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -414,8 +414,8 @@ class TransType(EnumRegistry, IntEnum):
414414
#: Simple Message Protocol [Leif Ekblad]
415415
SMP = 121
416416

417-
#: Simple Multicast Protocol (deprecated)) [Jon Crowcroft][draft-perlman-
418-
#: simple-multicast-03]
417+
#: Simple Multicast Protocol (deprecated)) [Jon
418+
#: Crowcroft][draft-perlman-simple-multicast-03]
419419
SM = 122
420420

421421
#: Performance Transparency Protocol [Michael Welzl]

‎pcapkit/const/sctp/chunk.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -80,8 +80,8 @@ class Chunk(EnumRegistry, IntEnum):
8080
#: Payload Data supporting Interleaving (I-DATA) [:rfc:`8260`]
8181
Payload_Data_supporting_Interleaving = 64
8282

83-
#: DTLS (TEMPORARY - registered 2026-02-20, expires 2027-02-20) [draft-ietf-
84-
#: tsvwg-sctp-dtls-chunk-01]
83+
#: DTLS (TEMPORARY - registered 2026-02-20, expires 2027-02-20)
84+
#: [draft-ietf-tsvwg-sctp-dtls-chunk-01]
8585
DTLS = 65
8686

8787
#: Reserved for IETF-defined Chunk Extensions [:rfc:`9260`]

‎pcapkit/const/sctp/payload_protocol_identifier.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,8 @@ class PayloadProtocolIdentifier(EnumRegistry, IntEnum):
7979
#: published.]
8080
Q_IPC_Q_2150_3 = 14
8181

82-
#: SIMCO <draft-kiesel-midcom-simco-sctp-00.txt> [draft-kiesel-midcom-simco-
83-
#: sctp-00][Sebastian Kiesel]
82+
#: SIMCO <draft-kiesel-midcom-simco-sctp-00.txt>
83+
#: [draft-kiesel-midcom-simco-sctp-00][Sebastian Kiesel]
8484
SIMCO_draft_kiesel_midcom_simco_sctp_00_txt = 15
8585

8686
#: DDP Segment Chunk [:rfc:`5043`]
@@ -241,7 +241,7 @@ class PayloadProtocolIdentifier(EnumRegistry, IntEnum):
241241
#: 3GPP E1 Application Protocol (E1AP) [ 3GPP TS 38.463][Yang Xudong]
242242
PayloadProtocolIdentifier_3GPP_E1_Application_Protocol = 64
243243

244-
#: ELE2 Lawful Interception [http://ele2.io][Damir Franusic]
244+
#: ELE2 Lawful Interception [http://ele2.io] [Damir Franusic]
245245
ELE2_Lawful_Interception = 65
246246

247247
#: 3GPP NGAP over DTLS over SCTP [ 3GPP TS 38.413][Yang Xudong]
@@ -268,8 +268,8 @@ class PayloadProtocolIdentifier(EnumRegistry, IntEnum):
268268
#: 3GPP W1AP [3GPP TS 37.473][Lionel Morand]
269269
PayloadProtocolIdentifier_3GPP_W1AP = 73
270270

271-
#: DTLS Chunk Key-Management Messages [draft-westerlund-tsvwg-sctp-dtls-
272-
#: chunk-01]
271+
#: DTLS Chunk Key-Management Messages
272+
#: [draft-westerlund-tsvwg-sctp-dtls-chunk-01]
273273
DTLS_Chunk_Key_Management_Messages = 4242
274274

275275
@classmethod

‎pcapkit/vendor/default.py‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -275,14 +275,38 @@ class Vendor(metaclass=VendorMeta):
275275
def wrap_comment(text: 'str') -> 'str':
276276
"""Wraps long-length text to shorter lines of comments.
277277
278+
Sphinx renders a ``#:`` comment as reST, and its continuation lines
279+
join into one paragraph, so the text is made safe for that first:
280+
281+
* a space goes after a URL reference that another bracket follows
282+
directly, as in ``[http://ele2.io][Damir Franusic]``. docutils reads
283+
``]`` and ``[`` as URL characters, so the autolink would run on into
284+
the next citation;
285+
* a leading enumerator, such as the ``(S)`` of ``(S) flag``, is
286+
backslash-escaped, since reST would render it as an enumerated list.
287+
288+
A line never breaks at a hyphen, which would render ``run-time`` as
289+
``run- time``. Only a word longer than a whole line is split inside.
290+
291+
.. versionchanged:: 1.5.0
292+
293+
Spaces a URL reference off the bracket after it and escapes a
294+
leading enumerator (:issue:`1846`), and no longer breaks a line at a
295+
hyphen (:issue:`1847`).
296+
278297
Args:
279298
text: Source text.
280299
281300
Returns:
282301
Wrapped comments.
283302
284303
"""
285-
return '\n #: '.join(textwrap.wrap(text.strip(), 76))
304+
text = re.sub(r'(://[^\s\[\]]*\])(?=\[)', r'\1 ', text.strip())
305+
# NOTE: the enumerator forms docutils recognises -- ``1.``, ``(a)``,
306+
# ``iv)``, ``#.`` and so on -- each followed by a space or nothing.
307+
text = re.sub(r'\A(?=(?:\((?:[0-9]+|[a-zA-Z]|[ivxlcdm]+|[IVXLCDM]+|#)\)'
308+
r'|(?:[0-9]+|[a-zA-Z]|[ivxlcdm]+|[IVXLCDM]+|#)[.)])(?: |\Z))', r'\\', text)
309+
return '\n #: '.join(textwrap.wrap(text, 76, break_on_hyphens=False))
286310

287311
@staticmethod
288312
def split_references(text: 'str') -> 'list[str]':

0 commit comments

Comments
 (0)