This is an automated email from the ASF dual-hosted git repository.
bneradt pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 0c323385b8 Fix Sphinx documentation build warnings (#12709)
0c323385b8 is described below
commit 0c323385b804ea4e4b2204a28366e4dc096848c3
Author: Brian Neradt <[email protected]>
AuthorDate: Wed Dec 3 20:03:42 2025 -0600
Fix Sphinx documentation build warnings (#12709)
Add missing C++ enumerators to the nitpick_ignore list in conf.cmake.in.py
to resolve 162 broken cross-reference warnings. The warnings were caused by
references to API enumerators (hook IDs, return values, milestones, etc.)
that are defined in C++ headers but not formally documented in Sphinx. Also
cleaned up duplicate entries and organized the list with category comments
for maintainability. With this change, the docs now build without warnings.
---
doc/conf.cmake.in.py | 83 ++++++++++++++++++++++++++++++++++++++++++++--------
1 file changed, 71 insertions(+), 12 deletions(-)
diff --git a/doc/conf.cmake.in.py b/doc/conf.cmake.in.py
index ebc2a74c8a..f75f3b5d8c 100644
--- a/doc/conf.cmake.in.py
+++ b/doc/conf.cmake.in.py
@@ -207,6 +207,7 @@ pygments_style = 'default'
nitpicky = True
nitpick_ignore = [
+ # Standard C/C++ types
('cpp:identifier', 'int64_t'),
('cpp:identifier', 'uint64_t'),
('cpp:identifier', 'uint8_t'),
@@ -215,26 +216,84 @@ nitpick_ignore = [
('cpp:identifier', 'ssize_t'),
('cpp:identifier', 'sockaddr'),
('cpp:identifier', 'time_t'),
- ('cpp:identifier', 'time_t'),
+ # External library types
('cpp:identifier', 'swoc'),
('cpp:identifier', 'swoc::Rv<Directive::Handle>'),
('cpp:identifier', 'Directive::Handle'),
('cpp:identifier', 'CfgStaticData'),
('cpp:identifier', 'YAML'),
('cpp:identifier', 'YAML::Node'),
- ('cpp:identifier', 'swoc'),
- ('cpp:identifier', 'swoc::TextView'),
- ('cpp:identifier', 'swoc'),
('cpp:identifier', 'swoc::TextView'),
- ('cpp:identifier', 'YAML'),
- ('cpp:identifier', 'YAML::Node'),
- ('cpp:identifier', 'swoc'),
('cpp:identifier', 'swoc::Errata'),
- ('cpp:identifier', 'CfgStaticData'),
- ('cpp:identifier', 'T'), # template arg
- ('cpp:identifier', 'F'), # template arg
- ('cpp:identifier', 'Args'), # variadic template arg
- ('cpp:identifier', 'Rest'), # variadic template arg
+ # Template arguments
+ ('cpp:identifier', 'T'),
+ ('cpp:identifier', 'F'),
+ ('cpp:identifier', 'Args'),
+ ('cpp:identifier', 'Rest'),
+ # Event system
+ ('cpp:identifier', 'EVENT_IMMEDIATE'),
+ # API return values
+ ('cpp:enumerator', 'TS_SUCCESS'),
+ ('cpp:enumerator', 'TS_ERROR'),
+ # HTTP hook IDs
+ ('cpp:enumerator', 'TS_HTTP_READ_REQUEST_HDR_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_READ_RESPONSE_HDR_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_SEND_REQUEST_HDR_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_SEND_RESPONSE_HDR_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_OS_DNS_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_PRE_REMAP_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_POST_REMAP_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_TXN_START_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_TXN_CLOSE_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_SSN_START_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_SSN_CLOSE_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_READ_CACHE_HDR_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_SELECT_ALT_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_REQUEST_TRANSFORM_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_RESPONSE_TRANSFORM_HOOK'),
+ ('cpp:enumerator', 'TS_HTTP_REQUEST_BUFFER_READ_COMPLETE_HOOK'),
+ # SSL/TLS hook IDs
+ ('cpp:enumerator', 'TS_SSL_CLIENT_HELLO_HOOK'),
+ ('cpp:enumerator', 'TS_SSL_SERVERNAME_HOOK'),
+ ('cpp:enumerator', 'TS_SSL_SNI_HOOK'),
+ ('cpp:enumerator', 'TS_SSL_CERT_HOOK'),
+ ('cpp:enumerator', 'TS_VCONN_START_HOOK'),
+ # Lifecycle hooks
+ ('cpp:enumerator', 'TS_LIFECYCLE_SSL_SECRET_HOOK'),
+ # Transaction milestones
+ ('cpp:enumerator', 'TS_MILESTONE_SM_START'),
+ ('cpp:enumerator', 'TS_MILESTONE_UA_CLOSE'),
+ ('cpp:enumerator', 'TS_MILESTONE_SERVER_CLOSE'),
+ ('cpp:enumerator', 'TS_MILESTONE_PLUGIN_ACTIVE'),
+ ('cpp:enumerator', 'TS_MILESTONE_PLUGIN_TOTAL'),
+ # HTTP types and status
+ ('cpp:enumerator', 'TS_HTTP_TYPE_UNKNOWN'),
+ ('cpp:enumerator', 'TS_HTTP_STATUS_NONE'),
+ ('cpp:enumerator', 'TS_HTTP_STATUS_BAD_REQUEST'),
+ # Parse results
+ ('cpp:enumerator', 'TS_PARSE_ERROR'),
+ ('cpp:enumerator', 'TS_PARSE_DONE'),
+ ('cpp:enumerator', 'TS_PARSE_CONT'),
+ # VConnection
+ ('cpp:enumerator', 'TS_VC_CLOSE_ABORT'),
+ # Record types and data types
+ ('cpp:enumerator', 'TS_RECORDTYPE_NULL'),
+ ('cpp:enumerator', 'TS_RECORDTYPE_CONFIG'),
+ ('cpp:enumerator', 'TS_RECORDDATATYPE_INT'),
+ ('cpp:enumerator', 'TS_RECORDDATATYPE_FLOAT'),
+ ('cpp:enumerator', 'TS_RECORDDATATYPE_STRING'),
+ ('cpp:enumerator', 'TS_RECORDDATATYPE_COUNTER'),
+ ('cpp:enumerator', 'TS_RECORDCHECK_STR'),
+ # Remap plugin return values
+ ('cpp:enumerator', 'TSREMAP_DID_REMAP'),
+ ('cpp:enumerator', 'TSREMAP_DID_REMAP_STOP'),
+ ('cpp:enumerator', 'TSREMAP_NO_REMAP'),
+ ('cpp:enumerator', 'TSREMAP_NO_REMAP_STOP'),
+ ('cpp:enumerator', 'TSREMAP_ERROR'),
+ ('cpp:enumerator', 'TSREMAP_CONFIG_RELOAD_FAILURE'),
+ ('cpp:enumerator', 'TSREMAP_CONFIG_RELOAD_SUCCESS_PLUGIN_USED'),
+ ('cpp:enumerator', 'TSREMAP_CONFIG_RELOAD_SUCCESS_PLUGIN_UNUSED'),
]
# Autolink issue references.
