gnunet-handbook

The GNUnet Handbook
Log | Files | Refs

commit 125a11d9113beac47b8833abeeb23259dad64416
parent 76535c198ac68ce0dbcb059e4f356d5fb53289b1
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date:   Thu, 19 Nov 2026 00:55:36 +0100

Update httpdomain missing files

Diffstat:
A_exts/httpdomain/LICENSE | 28++++++++++++++++++++++++++++
A_exts/httpdomain/README | 46++++++++++++++++++++++++++++++++++++++++++++++
A_exts/httpdomain/_path_signature.py | 36++++++++++++++++++++++++++++++++++++
A_exts/httpdomain/websocket.py | 246+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 356 insertions(+), 0 deletions(-)

diff --git a/_exts/httpdomain/LICENSE b/_exts/httpdomain/LICENSE @@ -0,0 +1,28 @@ +If not otherwise noted, the extensions in this package are licensed +under the following license. + +Copyright (c) 2010 by the contributors (see AUTHORS file). +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/_exts/httpdomain/README b/_exts/httpdomain/README @@ -0,0 +1,46 @@ +Bundled copy of sphinxcontrib-httpdomain +======================================== + +Upstream: https://github.com/sphinx-contrib/httpdomain +Version: 2.2.1 (PyPI "sphinxcontrib-httpdomain", released 2026-10-14) +License: BSD-2-Clause, see LICENSE +Requires: Sphinx 8.1.3 or later, Python 3.10 or later (upstream's + requirements) + +conf.py loads it as the extension "httpdomain"; it is found through the +_exts/ entry that conf.py adds to sys.path. The handbook uses it in +developers/rest-api/namestore.rst. + +Files +----- + +__init__.py, _path_signature.py and websocket.py are copied unchanged +from the package sphinxcontrib/httpdomain/ in the upstream wheel, except +for the local change below. + +Not included: + +- sphinxcontrib/autohttp/ (autoflask, autobottle, autotornado): not used + by the handbook, and it needs Flask, Bottle or Tornado. +- sphinxcontrib/httpdomain/locale/: the Spanish and French translations + of the extension's own labels. The handbook is in English. + +Local changes +------------- + +Re-apply these when updating: + +- __init__.py: HTTPDomain.indices is [] instead of [HTTPIndex], so that + no "HTTP Routing Table" page (http-routingtable.html) is generated. + The previously bundled version 1.7.0 had the same change. + +Updating +-------- + + pip download --no-deps sphinxcontrib-httpdomain==VERSION + unzip sphinxcontrib_httpdomain-VERSION-*.whl + +Copy the three files listed above from sphinxcontrib/httpdomain/ and +LICENSE from the .dist-info directory, re-apply the local changes, update +the version in this file, and check how developers/rest-api/namestore.rst +renders. diff --git a/_exts/httpdomain/_path_signature.py b/_exts/httpdomain/_path_signature.py @@ -0,0 +1,36 @@ +"""Shared rendering for HTTP and WebSocket path signatures.""" + +import re + +from sphinx import addnodes + + +path_signature_param_re = re.compile( + r'\((?:(?P<type>[^:)]+):)?(?P<name>[\w_]+)\)', re.VERBOSE +) + + +def render_path_signature(sig, signode): + """Render typed path parameters into *signode* and return the final path part. + + The return value intentionally mirrors the historical HTTP implementation. + """ + offset = 0 + path = None + for match in path_signature_param_re.finditer(sig): + path = sig[offset:match.start()] + signode += addnodes.desc_name(path, path) + params = addnodes.desc_parameterlist() + typ = match.group('type') + if typ: + typ += ': ' + params += addnodes.desc_annotation(typ, typ) + name = match.group('name') + params += addnodes.desc_parameter(name, name) + signode += params + offset = match.end() + if offset < len(sig): + path = sig[offset:len(sig)] + signode += addnodes.desc_name(path, path) + assert path is not None, 'no matches for sig: %s' % sig + return path diff --git a/_exts/httpdomain/websocket.py b/_exts/httpdomain/websocket.py @@ -0,0 +1,246 @@ +"""The WebSocket domain for documenting bidirectional connections.""" + +from dataclasses import dataclass +from hashlib import sha256 + +from docutils import nodes + +from sphinx import addnodes +from sphinx.directives import ObjectDescription, directives +from sphinx.domains import Domain, Index, ObjType +from sphinx.locale import get_translation +from sphinx.roles import XRefRole +from sphinx.util import logging +from sphinx.util.docfields import GroupedField, TypedField +from sphinx.util.nodes import make_refnode + +from ._path_signature import render_path_signature + + +_ = get_translation('httpdomain') +logger = logging.getLogger(__name__) + + +@dataclass(frozen=True) +class ConnectionRecord: + """The persisted, indexed data for one WebSocket connection.""" + + docname: str + synopsis: str + deprecated: bool + + +def connection_anchor(raw_signature): + """Return the stable anchor for an indexed WebSocket connection.""" + slug = nodes.make_id(raw_signature) or 'connection' + digest = sha256(raw_signature.encode('utf-8')).hexdigest() + return 'websocket-%s-%s' % (slug, digest) + + +class WebSocketConnection(ObjectDescription): + """Describe a WebSocket connection at an application path.""" + + doc_field_types = [ + TypedField('parameter', label=_('Parameters'), names=('param',)), + TypedField('queryparameter', label=_('Query Parameters'), names=('query',)), + GroupedField('servermessage', label=_('Messages sent by server'), + names=('server-message',)), + GroupedField('clientmessage', label=_('Messages sent by client'), + names=('client-message',)), + ] + + option_spec = { + 'deprecated': directives.flag, + 'noindex': directives.flag, + 'no-index': directives.flag, + 'addtoc': directives.flag, + 'synopsis': lambda value: value, + } + + def run(self): + # Sphinx 6 only recognizes ``noindex``. Sphinx 9 accepts both names, + # but normalizing here keeps the documented spelling cross-version. + if 'no-index' in self.options: + self.options['noindex'] = self.options.pop('no-index') + return super().run() + + def handle_signature(self, sig, signode): + if not sig.startswith('/'): + _, line = self.get_source_info() + logger.warning( + 'WebSocket connection paths must begin with "/": %s', sig, + location=(self.env.docname, line), + ) + raise ValueError + + prefix = 'WebSocket ' + signode += addnodes.desc_name(prefix, prefix) + render_path_signature(sig, signode) + signode['path'] = sig + signode['fullname'] = prefix + sig + return sig + + def needs_arglist(self): + return False + + def add_target_and_index(self, name, sig, signode): + connections = self.env.domaindata['websocket']['connections'] + record = ConnectionRecord( + self.env.docname, + self.options.get('synopsis', ''), + 'deprecated' in self.options, + ) + previous = connections.get(sig) + if previous is not None: + _, line = self.get_source_info() + logger.warning( + 'duplicate WebSocket connection definition %s in %s; ' + 'existing definition is in %s. Use :noindex: for an ' + 'intentional secondary rendering.', + sig, + self.env.doc2path(self.env.docname), + self.env.doc2path(previous.docname), + location=(self.env.docname, line), + ) + return + signode['ids'].append(connection_anchor(sig)) + connections[sig] = record + + def get_index_text(self, modname, name): + return '' + + def _object_hierarchy_parts(self, sig_node): + if ('addtoc' not in self.options or 'noindex' in self.options or + 'no-index' in self.options): + return () + path = sig_node.get('path') + if not path: + return () + return tuple(part for part in path.split('/') if part) + ( + 'WebSocket ' + path, + ) + + def _toc_entry_name(self, sig_node): + if not sig_node.get('_toc_parts'): + return '' + return sig_node['_toc_parts'][-1] + + +class WebSocketXRefRole(XRefRole): + """Cross-reference a WebSocket connection.""" + + def process_link(self, env, refnode, has_explicit_title, title, target): + if not has_explicit_title: + title = 'WebSocket ' + title + return title, target + + +class WebSocketIndex(Index): + """Generated index of indexed WebSocket connections.""" + + name = 'routingtable' + localname = _('WebSocket Routing Table') + shortname = _('WebSocket routing table') + + @staticmethod + def grouping_prefix(path): + parts = [part for part in path.split('/') if part] + return '/%s' % (parts[0] if parts else '') + + def generate(self, docnames=None): + content = {} + for path, record in sorted(self.domain.connections.items()): + entries = content.setdefault(self.grouping_prefix(path), []) + entries.append([ + 'WebSocket ' + path, + 0, + record.docname, + connection_anchor(path), + '', + _('Deprecated') if record.deprecated else '', + record.synopsis, + ]) + return sorted(content.items()), True + + +class WebSocketDomain(Domain): + """WebSocket documentation domain.""" + + name = 'websocket' + label = 'WebSocket' + data_version = 1 + + object_types = { + 'connection': ObjType('connection', 'connection'), + } + directives = { + 'connection': WebSocketConnection, + } + roles = { + 'connection': WebSocketXRefRole(), + } + initial_data = { + 'connections': {}, + } + indices = [WebSocketIndex] + + @property + def connections(self): + return self.data['connections'] + + def clear_doc(self, docname): + for signature, record in list(self.connections.items()): + if record.docname == docname: + del self.connections[signature] + + def resolve_xref(self, env, fromdocname, builder, typ, target, + node, contnode): + if not target.startswith('/'): + logger.warning( + 'WebSocket connection targets must begin with "/": %s', + target, + location=node, + ) + return contnode + + record = self.connections.get(target) + if record is None: + return contnode + return make_refnode( + builder, + fromdocname, + record.docname, + connection_anchor(target), + contnode, + 'WebSocket ' + target, + ) + + def resolve_any_xref(self, env, fromdocname, builder, target, node, + contnode): + return [] + + def get_objects(self): + for signature, record in self.connections.items(): + yield ( + signature, + signature, + 'connection', + record.docname, + connection_anchor(signature), + 1, + ) + + def merge_domaindata(self, docnames, otherdata): + for signature, record in otherdata['connections'].items(): + previous = self.connections.get(signature) + if previous is not None and previous != record: + logger.warning( + 'duplicate WebSocket connection definition %s in %s; ' + 'existing definition is in %s. Use :noindex: for an ' + 'intentional secondary rendering.', + signature, + self.env.doc2path(record.docname), + self.env.doc2path(previous.docname), + ) + continue + self.connections[signature] = record