From ab86cd396f02e15d6f97f94b6f7baf5bcb0b52d8 Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Tue, 1 Sep 2026 23:13:26 -0600 Subject: [PATCH] Correct README claims contradicted by the code - js/README.md: "Validated when the client is built - the only place this package throws" is wrong. js/src/client.ts's `requirePath` throws `github-docs: ... is not a published document` from `webUrl` and `rawUrl` when the target is not in the catalogue. Verified against the built package: `createDocsClient({repo:'acme-guild/handbook', documents:['handbook/rules.md']}) .webUrl('nope')` throws, while `.fetchMarkdown('nope')` returns `{status:'not-listed'}`. - python/README.md and the root README: `python3 -m unittest discover -s tests -v` could not work as written from a fresh clone -- nothing puts python/src on sys.path, so discovery collects one error instead of 31 tests. CI installs the package first (.github/workflows/ci.yml: `python -m pip install .`). Added PYTHONPATH=src; 31 tests pass. - Root README: both development lines were written to run from the repo root, but `cd python` after `cd js` resolves to js/python. Wrapped each in a subshell; both verified from the repo root. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_019KfUfNYTjPUrGcJnS5Ha23 --- README.md | 4 ++-- js/README.md | 2 +- python/README.md | 3 ++- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4cab66d..0af74f4 100644 --- a/README.md +++ b/README.md @@ -111,10 +111,10 @@ this community's docs work" from drifting apart. ```bash # read side -cd js && npm install && npm test +(cd js && npm install && npm test) # write side -cd python && python3 -m unittest discover -s tests -v +(cd python && PYTHONPATH=src python3 -m unittest discover -s tests -v) ``` CI runs both on every push and pull request. diff --git a/js/README.md b/js/README.md index ba9bf31..0442fed 100644 --- a/js/README.md +++ b/js/README.md @@ -122,7 +122,7 @@ docs.resolveLink('rules.md', 'handbook/getting-started.md'); | Option | Default | What it does | |---|---|---| -| `repo` | *(required)* | `owner/repo`, or a GitHub URL. Validated when the client is built — the only place this package throws. | +| `repo` | *(required)* | `owner/repo`, or a GitHub URL. Validated when the client is built, and an unusable value throws there. (`webUrl` and `rawUrl` also throw, for a target that is not in the catalogue; `fetchMarkdown` returns `not-listed` instead.) | | `ref` | `'HEAD'` | The git ref to read. `HEAD` resolves to the default branch whatever it is called. | | `token` | none | A read token, for a private repository. Omit for a public one. | | `transport` | `'api'` with a token, `'raw'` without | Contents API vs `raw.githubusercontent.com`. | diff --git a/python/README.md b/python/README.md index 9c1b42b..e165142 100644 --- a/python/README.md +++ b/python/README.md @@ -134,7 +134,8 @@ a control that depends on somebody else's behaviour is not a control. ## Development ```bash -python3 -m unittest discover -s tests -v +# from python/, with src/ on the path — or after `pip install -e .` +PYTHONPATH=src python3 -m unittest discover -s tests -v ``` The tests mock `urllib.request.urlopen` with a small fake GitHub API keyed on