Skip to content

docs: document the PyPI install path in the guides, not just the README - #10

Merged
FZ2000 merged 1 commit into
mainfrom
docs/pypi-install-paths
Jul 31, 2026
Merged

docs: document the PyPI install path in the guides, not just the README#10
FZ2000 merged 1 commit into
mainfrom
docs/pypi-install-paths

Conversation

@FZ2000

@FZ2000 FZ2000 commented Jul 31, 2026

Copy link
Copy Markdown
Owner

Problem

0.1.0 shipped to PyPI as da-sync and the README was updated to match, but
docs/getting-started.md — the page the README explicitly sends new users to
— still documented only git clone + ./install.sh. The one file written for
people 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.sh is in the sdist but not the wheel. Both the
    tutorial and docs/guides/scheduling.md tell you to run
    ./install_schedule.sh, which a pipx user simply does not have. The
    script's own error message pointed only at ./install.sh.
  • The ./install.sh transcript was stale. The script prints a
    (N modules) suffix that the documented output had dropped.

Solution

  1. Getting-started now offers both install paths, with the clone kept as the
    option that also carries the scheduling script.
  2. Both scheduling sections say where to get install_schedule.sh, and note
    it drives whatever da is already on PATH (install_schedule.sh:112
    resolves it with command -v da), so no reinstall is needed. Its error
    message now names both paths.
  3. check_doc_references.py asserts any documented module count against
    dacli/, so the number cannot drift again.

Verification

Everything was checked against da-sync 0.1.0 installed from PyPI, run with
XDG_CONFIG_HOME/XDG_STATE_HOME pointed at a scratch directory.

  • All 29 README quick-tour commands resolve against the installed binary.
  • The docs/commands/config.md transcripts were replayed in the sandbox that
    page documents (/tmp/da-demo, client_id=12345). config show,
    config path, --config, every config get example, the <=8 chars
    masking rule and the exit codes all reproduce byte-for-byte — including
    --unmask writing to stderr, so the documented 2>/dev/null really does
    print nothing.
  • docs/commands/sync.md's --help block is byte-identical to the real
    output at the width the docs are generated for (width=78).
  • ./install.sh was run with DA_INSTALL_PREFIX redirected, which is how the
    missing (17 modules) suffix was found.
  • The new module-count check was watched failing on a wrong number
    (says 99, dacli/ has 17, exit 1) before being kept.
  • install_schedule.sh's new error path was executed with da off PATH.
  • 868 tests pass; check_doc_flags, check_doc_references,
    check_version_sync, check_discoverability, markdownlint (pinned
    0.45.0 + repo config) and lychee --include-fragments are all clean.

docs/commands/ examples are executed by tests/test_docs_examples.py;
getting-started.md is not, which is how the stale transcript survived.

🤖 Generated with Claude Code

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
FZ2000 merged commit 2a6de3e into main Jul 31, 2026
24 checks passed
@FZ2000
FZ2000 deleted the docs/pypi-install-paths branch July 31, 2026 10:14
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant