From b8671635cd891068afee81fde05bed880124ec85 Mon Sep 17 00:00:00 2001 From: Christophe Besson Date: Mon, 5 Oct 2026 10:36:18 +0200 Subject: docs: generate an HTTP API listing for the hub and the node control API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/MESHBAY_HTTP_API.md lists every route of the hub (by domain, with the authentication each requires) and of the node's loopback control API. It is written by docs/generate_http_api.py from the routes and their docstrings; test_http_api_doc.py fails when the file drifts from the code or when a route has no docstring, so a new route must say what it does. 79 routes had no docstring and get a one-line description; a few whose first line did not describe the route get a summary line. The login page's developer docs gain an API link next to Design and Protocol, in every language. README, MESHBAY_DESIGN.md (§0.1, §6.7, §7) and CLAUDE.md point to the listing; README also points to examples/. The examples scripts with a shebang become executable. Co-Authored-By: Claude Opus 5.5 --- packages/meshbay-hub/tests/test_http_api_doc.py | 30 +++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 packages/meshbay-hub/tests/test_http_api_doc.py (limited to 'packages/meshbay-hub/tests/test_http_api_doc.py') diff --git a/packages/meshbay-hub/tests/test_http_api_doc.py b/packages/meshbay-hub/tests/test_http_api_doc.py new file mode 100644 index 0000000..5568e63 --- /dev/null +++ b/packages/meshbay-hub/tests/test_http_api_doc.py @@ -0,0 +1,30 @@ +""" +docs/MESHBAY_HTTP_API.md is generated from the routes of the hub and of the +node's control API. A route added, removed or redescribed without running +`python docs/generate_http_api.py` fails here. +""" + +import importlib.util +from pathlib import Path + +GENERATOR = Path(__file__).resolve().parents[3] / "docs" / "generate_http_api.py" + + +def _generator(): + spec = importlib.util.spec_from_file_location("generate_http_api", GENERATOR) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +def test_the_api_listing_matches_the_routes(): + gen = _generator() + assert gen.OUT.read_text(encoding="utf-8") == gen.render(), ( + "docs/MESHBAY_HTTP_API.md is out of date: run python docs/generate_http_api.py") + + +def test_every_route_says_what_it_does(): + gen = _generator() + bare = [f"{gen.method(r)} {r.path}" for r in gen.hub_routes() + gen.node_routes() + if not gen.summary(r)] + assert not bare, f"give these routes a docstring, it is their line in the listing: {bare}" -- cgit v1.2.3