README: fix CSV column names + restructure Troubleshooting/Usage flow#10
Open
jcddc83 wants to merge 1 commit into
Open
README: fix CSV column names + restructure Troubleshooting/Usage flow#10jcddc83 wants to merge 1 commit into
jcddc83 wants to merge 1 commit into
Conversation
Factual fixes: - Output section listed CSV columns as "Post Title / Post URL / Broken Link / Error Type", but the code writes the snake_case form (post_title, post_url, broken_link, error_type via csv.DictWriter in checker.py). Replaced with the actual column names plus human-readable descriptions in a second table column. - "Example Output" block contained per-post "Checking N links..." and "Found N broken links in this post" lines which only appear when --verbose is passed (they're emitted via self._log without force=True). Relabeled the block as `$ ... --verbose ...` and added a one-liner noting which lines are suppressed without --verbose. Structural: - Moved Troubleshooting to after Usage / Example Output (was before Usage, which interrupted the "how do I use this?" reading flow). - Renamed "CLI Options" to "`check` Subcommand Options" and added a pointer to `substack-link-checker <subcommand> --help` for the other subcommands, whose flags weren't documented anywhere. - Removed run_link_checker.ps1 from the Subcommands table (it's a separate PowerShell wrapper, not a subcommand). Added a small "Scheduled / automated runs" subsection describing it. - Dropped "(Optional)" from the Authentication section heading; bot protection rejects most unauthenticated scans in practice, so the auth flow is more recommended than optional. Added a one-line note explaining when it's needed. Additions: - Quick Start now mentions `substack-link-checker demo` as an optional install smoke-test. - One-line mention of `--version` flag below the options table. - New "Importing Previous Results" subsection in Usage with example invocations for both .xlsx and .csv (the `import` subcommand was documented in the Subcommands table but never demonstrated). Docs only — no code or test changes. 38 pytest tests still pass.
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
2 participants
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.
Summary
README audit and cleanup following v1.1.0. Docs-only, no code or test changes.
Factual fixes
post_title,post_url,broken_link,error_type) — the names produced bycsv.DictWriterinchecker.py. Previously the README showed pretty-printed labels that don't match what users see when they open the report in Excel.Checking N links...andFound N broken links in this postlines only appear with--verbose. Relabeled the block accordingly and added a note about which lines are suppressed without it.Structural fixes
checkSubcommand Options and pointed at--helpfor the other subcommands (whose flags weren't documented anywhere).run_link_checker.ps1from the Subcommands table (it's a PowerShell wrapper, not a subcommand). Added a small Scheduled / automated runs subsection.Additions
substack-link-checker demoas a smoke-test step.--version.importsubcommand (Excel + CSV invocations).Test plan
ruff check .cleanpytest→ 38/38 passingsrc/substack_link_checker/import_history.pyto confirm flags matchGenerated by Claude Code