Skip to content

feat(cli): Add btw docs topics to list topics#194

Merged
gadenbuie merged 10 commits into
mainfrom
feat/cli-docs-topics
May 14, 2026
Merged

feat(cli): Add btw docs topics to list topics#194
gadenbuie merged 10 commits into
mainfrom
feat/cli-docs-topics

Conversation

@gadenbuie
Copy link
Copy Markdown
Collaborator

@gadenbuie gadenbuie commented May 14, 2026

❯ btw docs topics --help
List help topics and vignettes for a package

Usage: btw docs topics [OPTIONS] <PACKAGE>

Options:
  -o, --only <ONLY>   Limit output to "help" topics or "vignettes".
                      [default: ""] [type: string]
  --json / --no-json  Output as JSON with top-level keys "help" (array of
                      {topic_id, title, aliases[]}) and "vignettes" (array of
                      {vignette, title}).
                      [default: false]
                      Enable with `--json`.

Global options:
  --version / --no-version  Print btw version and exit. [default: false]
                            Enable with `--version`.

Arguments:
  <PACKAGE>  Package name.
btw docs topics dplyr
## Help topics


* `across` - Apply a function (or functions) across multiple columns
* `all_equal` - Flexible equality comparison for data frames
* `all_vars` - Apply predicate to all variables
* `args_by` - Helper for consistent documentation of '.by'
* `arrange` - Order rows using column values
* `arrange_all` - Arrange rows by a selection of variables
* `auto_copy` - Copy tables to same source, if necessary
* `backend_dbplyr` - Database and SQL generics.
* `band_members` - Band membership
* `base` - dplyr <-> base R
* `between` - Detect where values fall in a specified range
* `bind_cols` - Bind multiple data frames by column
* `bind_rows` - Bind multiple data frames by row
* `c_across` - Combine values from multiple columns
* `case-and-replace-when` - A general vectorised if-else
* `case_match` - A general vectorised 'switch()'
* `check_dbplyr` - dbplyr compatibility functions
* `coalesce` - Find the first non-missing element
* `colwise` - Column-wise operations
* `common_by` - Extract out common by variables
* `compute` - Force computation of a database query
* `consecutive_id` - Generate a unique identifier for consecutive combinations
* `context` - Information about the "current" group or variable
* `copy_to` - Copy a local data frame to a remote src
* `count` - Count the observations in each group
* `cross_join` - Cross join
* `cumall` - Cumulative versions of any, all, and mean
* `defunct` - Defunct functions
* `defunct-each` - Defunct functions for working with multiple columns
* `defunct-lazyeval` - Defunct standard evaluation functions
* `deprec-context` - Information about the "current" group or variable
* `desc` - Descending order
* `dim_desc` - Describing dimensions
* `distinct` - Keep distinct/unique rows
* `distinct_all` - Select distinct rows by a selection of variables
* `distinct_prepare` - Prepare for grouping and other operations
* `do` - Do anything
* `dplyr` - Introduction to dplyr
* `dplyr-locale` - Locale used by 'arrange()'
* `dplyr-package` - dplyr: A Grammar of Data Manipulation
* `dplyr_by` - Per-operation grouping with '.by'/'by'
* `dplyr_data_masking` - Data-masking
* `dplyr_extending` - Extending dplyr with new data frame subclasses
* `dplyr_tidy_select` - Argument type: tidy-select
* `explain` - Explain details of a tbl
* `filter` - Keep or drop rows that match a condition
* `filter-joins` - Filtering joins
* `filter_all` - Filter within a selection of variables
* `funs` - Create a list of function calls
* `glimpse` - Get a glimpse of your data
* `group_by` - Group by one or more variables
* `group_by_all` - Group by a selection of variables
* `group_by_drop_default` - Default value for .drop argument of group_by
* `group_cols` - Select grouping variables
* `group_data` - Grouping metadata
* `group_map` - Apply a function to each group
* `group_nest` - Nest a tibble using a grouping specification
* `group_split` - Split data frame by groups
* `group_trim` - Trim grouping structure
* `grouped_df` - A grouped data frame.
* `grouping` - Grouped data
* `ident` - Flag a character vector as SQL identifiers
* `if_else` - Vectorised if-else
* `in-packages` - Using dplyr in packages
* `join_by` - Join specifications
* `last_dplyr_warnings` - Show warnings from the last command
* `lead-lag` - Compute lagged or leading values
* `make_tbl` - Create a "tbl" object
* `mutate` - Create, modify, and delete columns
* `mutate-joins` - Mutating joins
* `mutate_all` - Mutate multiple columns
* `n_distinct` - Count unique combinations
* `na_if` - Convert values to 'NA'
* `near` - Compare two numeric vectors
* `nest_by` - Nest by one or more variables
* `nest_join` - Nest join
* `new_grouped_df` - Low-level construction and validation for the grouped_df and rowwise_df classes
* `nth` - Extract the first, last, or nth value from a vector
* `ntile` - Bucket a numeric vector into 'n' groups
* `order_by` - A helper function for ordering window function output
* `percent_rank` - Proportional ranking functions
* `pick` - Select a subset of columns
* `programming` - Programming with dplyr
* `progress_estimated` - Progress bar with estimated time.
* `pull` - Extract a single column
* `recode` - Recode values
* `recode-and-replace-values` - Recode and replace values
* `recoding-replacing` - Recoding columns and replacing values
* `reexports` - Objects exported from other packages
* `reframe` - Transform each group to an arbitrary number of rows
* `relocate` - Change column order
* `rename` - Rename columns
* `row_number` - Integer ranking functions
* `rows` - Manipulate individual rows
* `rowwise` - Group input by rows
* `same_src` - Figure out if two sources are the same (or two tbl have the same source)
* `sample_n` - Sample n rows from a table
* `scoped` - Operate on a selection of variables
* `select` - Keep or drop columns using their names and types
* `select_all` - Select and rename a selection of variables
* `setops` - Set operations
* `slice` - Subset rows using their positions
* `sql` - SQL escaping.
* `src` - Create a "src" object
* `src_tbls` - List all tbls provided by a source.
* `starwars` - Starwars characters
* `storms` - Storm tracks data
* `summarise` - Summarise each group down to one row
* `summarise_all` - Summarise multiple columns
* `tbl` - Create a table from a data source
* `tbl_ptype` - Return a prototype of a tbl
* `tbl_vars` - List variables provided by a tbl.
* `tidyeval-compat` - Other tidy eval tools
* `top_n` - Select top (or bottom) n rows (by value)
* `transmute` - Create, modify, and delete columns
* `two-table` - Two-table verbs
* `vars` - Select variables
* `when-any-all` - Elementwise 'any()' and 'all()'
* `window-functions` - Window functions
* `with_groups` - Perform an operation with temporary groups
* `with_order` - Run a function with one order, translating result back to original order

Use `btw docs help dplyr::<topic>` to read a help page.


## Vignettes

* `colwise` - Column-wise operations
* `base` - dplyr <-> base R
* `grouping` - Grouped data
* `dplyr` - Introduction to dplyr
* `programming` - Programming with dplyr
* `recoding-replacing` - Recoding columns and replacing values
* `rowwise` - Row-wise operations
* `two-table` - Two-table verbs
* `in-packages` - Using dplyr in packages
* `window-functions` - Window functions

Use `btw docs vignette dplyr --name <name>` to read a vignette.

gadenbuie added 10 commits May 13, 2026 17:21
- Add `btw docs topics <pkg> [--only help|vignettes]` as a dedicated
  discovery command that lists help topics and vignettes for a package
  in two clearly-labelled sections
- Remove the ambiguous `{pkg}` brace syntax from `btw docs help`;
  topic listing is now handled exclusively by `btw docs topics`
- Update `btw docs help <TOPIC>` description to drop the `{package}`
  reference and clarify `pkg::topic` scoping
- Add `btw_docs_topics()` implementation with input validation on
  `--only` (accepts "", "help", or "vignettes")
- Update SKILL.md to document the new command and drop the brace syntax
- Add tests for all three `--only` modes and `--help` snapshot
- Add `## Help topics` and `## Vignettes` section headings
- Replace JSON output with YAML-style key: value pairs, one entry per
  topic/vignette, blank line between entries
- Rewrite `btw_docs_topics()` to call `_impl` functions directly and
  pull structured data from `extra$data` rather than consuming the
  JSON `@value` strings
- Add `format_as_yaml_rows()` helper in exec/btw.R
Replace YAML-style key/value rows with compact markdown list items:

  * `topic_id` - Title

Simpler, more readable, and consistent with how markdown lists
are used elsewhere in btw output. Replaces format_as_yaml_rows()
with a one-liner format_as_md_list() helper.
- Show aliases parenthetically after the topic ID when they differ:
    * `mutate` *(also: mutate_all, mutate_at, mutate_if)* - Create, modify, and delete columns
- Drop the format_as_md_list() helper; write the formatting logic
  inline in btw_docs_topics() where it's used
- Use full df (with aliases column) for help topics instead of
  pre-subsetting to topic_id + title
When a package has no vignettes, the abort from
`btw_tool_docs_available_vignettes_impl()` was propagating before the
`## Vignettes` heading was printed, causing the error message to appear
without its heading. Now the heading is printed first and the error is
caught locally so it renders as body text beneath it.
Outputs structured JSON with top-level keys "help" (array of
{topic_id, title, aliases[]}) and "vignettes" (array of {vignette,
title}), compatible with --only to limit which sections are included.
@gadenbuie gadenbuie merged commit bed0817 into main May 14, 2026
14 of 17 checks passed
@gadenbuie gadenbuie deleted the feat/cli-docs-topics branch May 14, 2026 14:28
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