Publish the supported API as a generated reference

[QuiteYellow]

localthings#435 contains a section headed "What the library provides", verified there against released wheels and carrying its own list of gaps. @mbillow unzipped wheels to establish what this library exposes, and kept the result in his issue tracker. That is the gap this closes.

The README offered an eleven-row table of module responsibilities. 209 public names sit across those modules, of which 100 are supported, and that distinction lived only in tests/test_public_api_contract.py, where no consumer reads it.

What is here

docs/api.md: every supported name, with the signature and summary read off the object. Classes list their methods, constants show their values.

The layout took a second pass, because the first cut was a flat list of 106 equal-weight entries. Four things about it were measurably hard to use:

• DtlsCoapSession's signature is 413 characters and it was inside an h4. No heading survives that, and the anchor becomes an unusable slug. Signatures moved into fenced blocks under bare-name headings.
• 26 constants were 26 headings, each spending a heading and a detail line to say DEAD is 'dead'. One table per module now.
• Alphabetical order put dtls_probe's ten constants above its five functions. Classes lead, then functions, then the table.
• Headings skipped h2 to h4 and there was no contents list, so fifteen flat module names were the only way in. Six layers and a contents list now.

The layer grouping is the one piece of hand-maintained judgement, so a test asserts every supported module appears in exactly one layer. Another checks the contents anchors resolve to headings, with the slugs verified against GitHub's own renderer.

tools/api_contract.py holds the mapping, moved out of the test so the generator and the test read one source. tests/test_share_safety.py already imports from tools/, so the direction is established.

Four tests keep the page honest. One re-renders and compares, so a renamed argument or a new supported name fails the suite, which is where a stale page gets caught. The others assert every declared name reaches the page, every module is laid out once, and every contents anchor resolves. I checked the drift and anchor tests bite by breaking the file each way and watching them fail.

What writing it found

The two discovery functions now cross-reference each other in their docstrings, which is what help() and an IDE tooltip show. #20 spent five weeks dialling a plaintext response port as a DTLS target, and I said there that the similar names were mine to make clearer. The page separates them through the module and function summaries; the docstrings now say it outright.

diagnose_dtls_handshake was missing from the contract. LocalThings imports it at config_flow.py:537, and I extended it with auth= and documented it in 0.1.17 this week, all while it sat undeclared. It is declared now. I audited the other sixteen names I have pointed anyone at, publicly or in release notes, and the rest were already there.

probe stays undeclared. LocalThings imports that too, at config_flow.py:405, but it is the deprecated adapter, probe(stateless=False) already warns, and this list is a promise to keep a name working. That leaves LocalThings importing a name outside the contract, which is a conversation for #435 and not this PR.

Three rendering faults, each of which made the page wrong

Naming them because they are the kind of thing a generated page hides:

• inspect.getdoc falls back to an instance's type docstring, so every outcome constant rendered as str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str. Constants now show their value, which is what a reader wants from DEAD anyway.
• from __future__ import annotations leaves stringized annotations, so signatures read identity: 'bytes' until eval_str=True resolved them.
• Cutting a summary at the first . turned "exits (i.e. socket dies)" into "exits (i." and "RFC 7252 §4.4 CoAP Ping" into "RFC 7252 §4.". Summaries take the first paragraph whole, capped at 200 characters.

RST double backticks are also normalised to single ones, purely as house style. I had this written up as a fourth fault until I checked it against GitHub's renderer: x is already a code span in Markdown, so it rendered correctly all along.

A generated page has to render the same everywhere

The first push passed on 3.14 and failed on 3.11, 3.12 and 3.13, because inspect renders the same annotations differently by version and I had committed a 3.14 render. Two causes, both now normalised:

• typing.Optional[X] renders as X | None from 3.14 and as Optional[X] before it. Twelve lines differed. Signatures canonicalise it by bracket matching, since the inner type nests as in Optional[Callable[[], bool]] and a regex mis-slices that.
• inspect.signature on an Enum class returns EnumMeta.__call__: (*values) on 3.14, and the whole functional API on 3.11. SamsungServerRole now lists its members and values, which is what an enum is for, and carries no signature to differ over.

Output is byte-identical on 3.11, 3.12, 3.13 and 3.14, each checked against a real interpreter, and the suite passes on all four plus the dependency floor.

--check prints a unified diff now. It reported only "stale" before, which turned an interpreter-specific render into a guess-and-push loop against CI when the cause was one line each time.

The reference is reachable now

"Supported library imports" sat at line 474 of 1180, as an h3 child of "BLE OCF framing": the list of names downstream may import, parented under a codec section. It is an h2 directly after the library quick start now, and a Documentation block near the top links docs/api.md alongside the two device-research files.

The h3 sections that followed it are still under "BLE OCF framing", which is the same misparenting one level along. Splitting this README by audience is its own change.

One pre-existing wrinkle, now slightly wider

tests/ ships in the sdist and tools/ does not, so a test importing from tools/ cannot be collected from a bare sdist. tests/test_share_safety.py already had this, and I verified both files now fail to collect from an extracted sdist. CI does not catch it, because the sdist job imports the package without running the tests. Shipping tools/ alongside the tests it supports would fix it, and that belongs in its own change.

Validation

796 tests pass on Python 3.11, 3.12, 3.13 and 3.14, and on both CI dependency sets. check_share_safety.py is clean, and the build plus distribution check pass. docs/api.md and tools/ stay out of the sdist, matching the existing policy.