docs: document the PyPI install path in the guides, not just the README - #10
Merged
Conversation
0.1.0 went to PyPI as `da-sync` and the README was updated, but the getting-started guide — the page the README sends new users to — still documented only `git clone` + `./install.sh`. The one file aimed at people who have never used the tool was the one file that never mentioned the published package. Verified against the real thing rather than by reading: * Installed `da-sync` 0.1.0 from PyPI into a throwaway venv and ran the documented commands with `XDG_CONFIG_HOME`/`XDG_STATE_HOME` pointed at a scratch directory. All 29 README quick-tour commands resolve. * Replayed the `docs/commands/config.md` transcripts in the sandbox the page documents (`/tmp/da-demo`, `client_id=12345`). `config show`, `config path`, `--config`, every `config get` example, the masking rule and the exit codes reproduce byte-for-byte — including `--unmask` writing to stderr, so `2>/dev/null` prints nothing. * Ran `./install.sh` with `DA_INSTALL_PREFIX` redirected. Its output carries a `(N modules)` suffix the transcript had dropped. Three fixes: 1. Getting-started gains the PyPI path, with the clone kept as the option that also carries the scheduling script. 2. `install_schedule.sh` is in the sdist but not the wheel, so `pipx` users cannot run `./install_schedule.sh` as the guides instruct. Both pages now say where to get it; the script's "not found on PATH" error names both install paths. 3. The `(N modules)` count is asserted by `check_doc_references` against `dacli/`. Watched it fail on a wrong number before keeping it. `docs/commands/` examples are executed by `tests/test_docs_examples.py`; `getting-started.md` is not, which is how the stale transcript survived. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
FZ2000
added a commit
that referenced
this pull request
Aug 1, 2026
…#11) The 0.1.0 project page on PyPI still carries the pre-launch README: **Option B — pip install.** Not published yet. Use Option A for now. That is on the page of the published package. A project description is frozen into the uploaded artifact, and PyPI offers no way to edit one, so the README corrections in #7 and #10 stay invisible to anyone who lands on PyPI until a new version is uploaded. That is the whole reason for this release: documentation only, no code changes. Bumped `dacli.__version__` (pyproject reads it via `attr`), CITATION.cff, and the CHANGELOG section title. `check_version_sync` caught three stale spots a manual bump would have shipped: the generated `docs/reference/cli.md` still embedded 0.1.0, and two `da-cli 0.1.0` transcripts in getting-started — one of them the `da --version` block added only yesterday. Regenerated the reference and corrected both. Verified with a clean 3.14 interpreter, asserting it imported the repo's `dacli` rather than the installed one: * `check_version_sync --tag v0.1.1` passes; `--tag v0.1.0` is refused with "does not match dacli.__version__", which is the guard release.yml relies on before it builds anything. * doc-flags, doc-references and discoverability all pass. * no test hardcodes a version — they read `dacli.__version__`. Co-authored-by: FZ2000 <frank@example.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
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
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.
Problem
0.1.0 shipped to PyPI as
da-syncand the README was updated to match, butdocs/getting-started.md— the page the README explicitly sends new users to— still documented only
git clone+./install.sh. The one file written forpeople who have never used the tool was the one file that never mentioned the
published package.
Two further gaps surfaced while verifying it:
install_schedule.shis in the sdist but not the wheel. Both thetutorial and
docs/guides/scheduling.mdtell you to run./install_schedule.sh, which apipxuser simply does not have. Thescript's own error message pointed only at
./install.sh../install.shtranscript was stale. The script prints a(N modules)suffix that the documented output had dropped.Solution
option that also carries the scheduling script.
install_schedule.sh, and noteit drives whatever
dais already onPATH(install_schedule.sh:112resolves it with
command -v da), so no reinstall is needed. Its errormessage now names both paths.
check_doc_references.pyasserts any documented module count againstdacli/, so the number cannot drift again.Verification
Everything was checked against
da-sync0.1.0 installed from PyPI, run withXDG_CONFIG_HOME/XDG_STATE_HOMEpointed at a scratch directory.docs/commands/config.mdtranscripts were replayed in the sandbox thatpage documents (
/tmp/da-demo,client_id=12345).config show,config path,--config, everyconfig getexample, the<=8 charsmasking rule and the exit codes all reproduce byte-for-byte — including
--unmaskwriting to stderr, so the documented2>/dev/nullreally doesprint nothing.
docs/commands/sync.md's--helpblock is byte-identical to the realoutput at the width the docs are generated for (
width=78)../install.shwas run withDA_INSTALL_PREFIXredirected, which is how themissing
(17 modules)suffix was found.(
says 99, dacli/ has 17, exit 1) before being kept.install_schedule.sh's new error path was executed withdaoffPATH.check_doc_flags,check_doc_references,check_version_sync,check_discoverability,markdownlint(pinned0.45.0 + repo config) and
lychee --include-fragmentsare all clean.docs/commands/examples are executed bytests/test_docs_examples.py;getting-started.mdis not, which is how the stale transcript survived.🤖 Generated with Claude Code