readability-cli 0.6.0__tar.gz → 0.7.0__tar.gz

{readability_cli-0.6.0 → readability_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readability-cli
-Version: 0.6.0
+Version: 0.7.0
 Summary: A CLI to lint, format, and type-check code with Google-style defaults, and pull Google style guides in markdown format.
 Project-URL: Homepage, https://github.com/owahltinez/readability
 Project-URL: Repository, https://github.com/owahltinez/readability
@@ -27,7 +27,8 @@ and quick access to style conventions without browsing HTML pages.
 - **Sensible Defaults**: Bundled Google-style configurations for Ruff and
   Pyrefly are used automatically when a project does not define its own.
 - **Style Guides**: A `guide` command that fetches the latest Google style
-  guides (Python, Shell, C++, Java, JS/TS, Go, etc.) converted to Markdown.
+  guides (Python, Shell, C++, Java, JS/TS, Go, etc.) converted to Markdown,
+  navigable by outline and by section rather than read whole.
 - **Offline Mode**: Local caching of style guides for fast, offline access,
   kept fresh with a single `sync` command.
 
@@ -128,18 +129,77 @@ readability guide python --remote
 # Save a style guide to a file
 readability guide cpp --output cpp-style.md
 
-# Print where the guide already lives, to search it without copying it
-readability guide python --path
-grep -n "Naming" "$(readability guide python --path)"
+# Search a guide without printing it: the pipe carries it, you see matches
+readability guide python | grep -n "f-string"
 
 # Synchronize all supported style guides to the local cache
 readability sync
 ```
 
-A guide can exceed 100 KB, so `--path` is the cheap way to consult one: the
-file is already on disk, and searching it beats reading it whole or writing
-out a second copy. It is also what a coding agent should use, rather than
-redirecting the guide into a repository.
+A guide can exceed 100 KB, so printing one whole is rarely what you want.
+`--outline` and `--section` below cover navigating to a rule; piping to
+`grep` covers finding wording that no heading names. Neither leaves a copy
+behind, which is what a coding agent should do rather than redirecting a
+guide into the repository it is working on.
+
+### Navigating a Guide
+
+`--outline` lists a guide's headings and `--section` prints just one of them,
+which turns "read 200 KB" into "list the sections, fetch the one you need":
+
+```bash
+# List every heading, with the index to pass to --section
+readability guide cpp --outline
+
+# Only the top two levels, for a bird's eye view of a large guide
+readability guide cpp --outline --depth 2
+
+# Print one section: its heading and everything nested under it
+readability guide shell --section "Function Comments"
+readability guide cpp --section 10.4
+
+# Sections can be saved like whole guides can
+readability guide python --section "Imports" --output imports.md
+```
+
+A section reference can be any of the following:
+
+| Reference | Example |
+|-----------|---------|
+| Section index, as shown by `--outline` | `--section 2.2.4` |
+| Heading text, case-insensitive, or its slug | `--section "function comments"` |
+| A parent-scoped path, spaces around the `>` | `--section "Imports > Decision"` |
+
+Whole matches are preferred; a reference that matches nothing in full is
+retried as a substring of the heading text.
+
+Three of the shipped guides — Python, JavaScript, and Java — number their own
+sections, and those numbers are the index. A rule cited from the outline then
+matches the published guide exactly, including where the guide skips a
+number: the Python guide has no 2.15 at all, so its 2.16 is listed as 2.16
+rather than renumbered. The other eleven guides number nothing, so their
+index comes from each heading's position in the tree.
+
+Either way the index is unique, which is what makes a repeated heading
+addressable — `Definition`, `Pros`, `Cons`, and `Decision` appear under every
+rule in the Python guide. For a reference stored and used later, prefer a
+printed section number or the heading text over a positional index, since
+positional indices shift when an unnumbered guide is re-synced.
+
+A reference that matches several headings is reported rather than guessed at,
+listing the index and path of every candidate on stderr:
+
+```bash
+$ readability guide python --section Decision
+Error: 'Decision' matches 19 headings in the 'python' guide. Repeat with one of:
+  --section 2.1.4 (Python Language Rules > Lint > Decision)
+  --section 2.2.4 (Python Language Rules > Imports > Decision)
+  ...
+```
+
+Content goes to stdout and diagnostics to stderr, so both flags are safe to
+pipe. Headings inside fenced code blocks are ignored, which matters for the
+Shell and Python guides where `#` starts a comment.
 
 ### Supported Languages
 

{readability_cli-0.6.0 → readability_cli-0.7.0}/README.md

@@ -13,7 +13,8 @@ and quick access to style conventions without browsing HTML pages.
 - **Sensible Defaults**: Bundled Google-style configurations for Ruff and
   Pyrefly are used automatically when a project does not define its own.
 - **Style Guides**: A `guide` command that fetches the latest Google style
-  guides (Python, Shell, C++, Java, JS/TS, Go, etc.) converted to Markdown.
+  guides (Python, Shell, C++, Java, JS/TS, Go, etc.) converted to Markdown,
+  navigable by outline and by section rather than read whole.
 - **Offline Mode**: Local caching of style guides for fast, offline access,
   kept fresh with a single `sync` command.
 
@@ -114,18 +115,77 @@ readability guide python --remote
 # Save a style guide to a file
 readability guide cpp --output cpp-style.md
 
-# Print where the guide already lives, to search it without copying it
-readability guide python --path
-grep -n "Naming" "$(readability guide python --path)"
+# Search a guide without printing it: the pipe carries it, you see matches
+readability guide python | grep -n "f-string"
 
 # Synchronize all supported style guides to the local cache
 readability sync
 ```
 
-A guide can exceed 100 KB, so `--path` is the cheap way to consult one: the
-file is already on disk, and searching it beats reading it whole or writing
-out a second copy. It is also what a coding agent should use, rather than
-redirecting the guide into a repository.
+A guide can exceed 100 KB, so printing one whole is rarely what you want.
+`--outline` and `--section` below cover navigating to a rule; piping to
+`grep` covers finding wording that no heading names. Neither leaves a copy
+behind, which is what a coding agent should do rather than redirecting a
+guide into the repository it is working on.
+
+### Navigating a Guide
+
+`--outline` lists a guide's headings and `--section` prints just one of them,
+which turns "read 200 KB" into "list the sections, fetch the one you need":
+
+```bash
+# List every heading, with the index to pass to --section
+readability guide cpp --outline
+
+# Only the top two levels, for a bird's eye view of a large guide
+readability guide cpp --outline --depth 2
+
+# Print one section: its heading and everything nested under it
+readability guide shell --section "Function Comments"
+readability guide cpp --section 10.4
+
+# Sections can be saved like whole guides can
+readability guide python --section "Imports" --output imports.md
+```
+
+A section reference can be any of the following:
+
+| Reference | Example |
+|-----------|---------|
+| Section index, as shown by `--outline` | `--section 2.2.4` |
+| Heading text, case-insensitive, or its slug | `--section "function comments"` |
+| A parent-scoped path, spaces around the `>` | `--section "Imports > Decision"` |
+
+Whole matches are preferred; a reference that matches nothing in full is
+retried as a substring of the heading text.
+
+Three of the shipped guides — Python, JavaScript, and Java — number their own
+sections, and those numbers are the index. A rule cited from the outline then
+matches the published guide exactly, including where the guide skips a
+number: the Python guide has no 2.15 at all, so its 2.16 is listed as 2.16
+rather than renumbered. The other eleven guides number nothing, so their
+index comes from each heading's position in the tree.
+
+Either way the index is unique, which is what makes a repeated heading
+addressable — `Definition`, `Pros`, `Cons`, and `Decision` appear under every
+rule in the Python guide. For a reference stored and used later, prefer a
+printed section number or the heading text over a positional index, since
+positional indices shift when an unnumbered guide is re-synced.
+
+A reference that matches several headings is reported rather than guessed at,
+listing the index and path of every candidate on stderr:
+
+```bash
+$ readability guide python --section Decision
+Error: 'Decision' matches 19 headings in the 'python' guide. Repeat with one of:
+  --section 2.1.4 (Python Language Rules > Lint > Decision)
+  --section 2.2.4 (Python Language Rules > Imports > Decision)
+  ...
+```
+
+Content goes to stdout and diagnostics to stderr, so both flags are safe to
+pipe. Headings inside fenced code blocks are ignored, which matters for the
+Shell and Python guides where `#` starts a comment.
 
 ### Supported Languages
 

{readability_cli-0.6.0 → readability_cli-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "readability-cli"
-version = "0.6.0"
+version = "0.7.0"
 description = "A CLI to lint, format, and type-check code with Google-style defaults, and pull Google style guides in markdown format."
 readme = "README.md"
 requires-python = ">=3.12"