Move appliance compatibility and certificates out - #90
Merged
Merged
Conversation
Third and last step of the README split, leaving it a library document. docs/appliance-compatibility.md takes "Is your appliance compatible?", the tested combinations and the firmware-family caveat. docs/certificates.md takes how the AC14K_M credential is obtained, why it works and how durable it is. The certificate keeps an entry point in the README, as "Getting a certificate" under Authentication. A client certificate is a prerequisite for opening any session, and the README is also the PyPI description, so a pip install reader needs the one command rather than a link alone. The reasoning left; the command stayed. "How the app keeps in sync with the appliance" went to docs/bridge-demo.md, which is where it should have gone in #88. It describes the bridge's push versus poll behaviour and the diagnostic entities it publishes, so it sits with the architecture rather than between two appliance sections. The link test from #88 earned itself here: bridge-demo.md pointed at README.md#firmware-families-a-limitation, and that heading had just moved into the compatibility doc. GitHub serves a page with a stale fragment without complaint, so nothing else would have caught it. Both new files had their subsections promoted from h3 to h2, since with the h1 title above them they skipped a level. README 1188 lines at the start of the split, 804 now.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Last step of the README split. It was 1188 lines serving four audiences at once and doubling as the PyPI description; it is 804 now, and reads as a library document top to bottom.
docs/appliance-compatibility.mdtakes "Is your appliance compatible?", the tested combinations and the firmware-family caveat.docs/certificates.mdtakes how the AC14K_M credential is obtained, why it works, and how durable it is.The certificate keeps an entry point
A client certificate is a prerequisite for opening any session, and the README is what a
pip install smartthings-localreader gets. So "Getting a certificate" stays, as a subsection of Authentication: the onesetup_cert.pycommand and what it writes. The reasoning, the durability discussion and how to read the UUID by hand moved out. That is the asymmetry discussed when this was planned: bridge material left wholesale, certificate material left its depth and kept its entry.It also puts the two halves of the credential story next to each other for the first time. Obtaining one and passing one to the library used to be 560 lines apart under separate headings that both said "auth".
A correction to #88
"How the app keeps in sync with the appliance" went to
docs/bridge-demo.md, where it should have gone in #88. It describes the bridge's push versus poll behaviour and the diagnostic entities it publishes, so it belongs with the architecture. I classified it as protocol material on the first pass and left it sitting between two appliance sections.The link test earned itself
docs/bridge-demo.mdpointed atREADME.md#firmware-families-a-limitation, and that heading had just moved into the compatibility doc. GitHub serves a page with a stale fragment without complaint, so the test is the only thing that would have caught it. It failed, I repointed the link, it passed.Both new files also had their subsections promoted from
h3toh2, since with theh1title above them they skipped a level, which is the same fault this split has been fixing elsewhere.Validation
798 tests pass on Python 3.11, 3.12, 3.13 and 3.14, and on the dependency floor.
check_share_safety.pyis clean.docs/is now six files: the generated API reference, the bridge demo, compatibility, certificates, and the two device-research notes.