Improve docs + disable cli info for now.

R/outline.R

@@ -2,8 +2,23 @@
 #' Print interactive outline of file sections
 #'
 #' @description
-#' RStudio project, or directories
-#' This will fail if you are trying to map an unsaved file.
+#' THe outline functions return a data frame that contains details of file location.
+#'
+#' It also includes a print method that will provide a console output that will include [clickable hyperlinks](https://cli.r-lib.org/reference/links.html)
+#' in RStudio (or if your terminal supports it). It works with both (qR)md and R files.
+#'
+#' Outline elements include
+#' * Any code section
+#' * function definition (not shown in console by default)
+#' * `TODO` items
+#' * Parse cli hyperlinks
+#' * Plot or table titles
+#' * FIgures caption in Quarto documents (limited support for multiline caption currently)
+#' * test names
+#' * Indicator of recent modification
+#' * Colored output for
+#' * URL and gh issue detection and link creation.
+#'
 #'
 #' If `work_only` is set to `TRUE`, the function will only return outline of the `# WORK` comment
 #' in `path`. `work_only = TRUE` will have an effect on `pattern`.
@@ -17,10 +32,12 @@
 #' `proj_outline()` and `dir_outline()` are wrapper of `file_outline()`.
 #'
 #' The parser is very opinioneted and is not very robust as it is based on regexps.
-#' For a better file parser, explore other options, like [lightparser](https://thinkr-open.github.io/lightparser/), `{roxygen2}`
+#' For a better file parser, explore other options, like [lightparser](https://thinkr-open.github.io/lightparser/) for Quarto,  `{roxygen2}`
 #'
 #' Will show TODO items and will offer a link to [mark them as
-#' complete][complete_todo()]
+#' complete][complete_todo()].
+#'
+#'
 #' @param path,proj A character vector of file paths, a [project][proj_list()].
 #'   Defaults to active file, project or directory. `rstudioapi::documentPath()`
 #' @param pattern A string or regex to search for in the outline. If
@@ -448,7 +465,7 @@ keep_outline_element <- function(.data) {
       # What to keep in .R files
       (!is_md & is_section_title_source) |
       # What to keep anywhere
-      is_cli_info | is_tab_or_plot_title | is_todo_fixme | is_test_name | is_cross_ref | is_function_def
+       is_tab_or_plot_title | is_todo_fixme | is_test_name | is_cross_ref | is_function_def # | is_cli_info # TODO reanable cli info
   )
   dat$simplify_news <- NULL
   dat

TODO.R

@@ -6,6 +6,7 @@
 # TODO [outline] make ggtitle work
 # TODO [outline] show extra msg only for some, but in file outline, not in proj?
 # TODO [outline] detect help calls and apply markup. `?fs::file_show` disregard finishing `.` (not followed by dot)
+# TODO [outline] renable cli info.
 # TODO escape_markup doesn't work with complex operation {{x^2}} for example. Maybe if detecting something complex, use cli_escape function. escape-complex-markyp branch created to try to address this.
 # TODO [outline] avoid evaluating in current env.
 # TODO wrap regexps in functions
@@ -21,3 +22,4 @@
 # TODO [delete] generated files
 # TODO [proj_file] to accesss data (return the path in this case?)
 # TODO [check_referenced_files] doesn't check for {.file R/file.R}
+# TODO explain rationale behind `work_only`. Suggest to transform to TODO if this item is no longer critical. `work_only` goal is to show you exactly where you need to do work

inst/example-file/outline-script.R

@@ -10,6 +10,7 @@ ggplot(mtcars, aes(x = vs, y = mpg)) +
   )
 # TODO improve this Viz!
 
+# file_outline() is a workaround for rstudio/rstudioapi#153
 f_example <- function(x) {
   x ** 2
 }

tests/testthat/_snaps/outline.md

@@ -21,7 +21,6 @@
       `i` A true one
       `i` TODO Create a new version- `Donev?`
       `i` Read my streets (<https://https://en.wikipedia.org/wiki/Street_art>) data
-      `i` Refer to google (<https://google.com>)
       `i` Roxygen section
       `i` Section title
       `i` Write my streets