improve documentation of search

R/screenshots.R

@@ -1,9 +1,12 @@
 library("chromote")
 
-screenshot <- function(b, path,
-                       selector = "html",
-                       cliprect = c(top = 0, left = 0, width = 1920, height = 1080),
-                       expand = NULL) {
+screenshot <- function(
+  b,
+  path,
+  selector = "html",
+  cliprect = c(top = 0, left = 0, width = 1920, height = 1080),
+  expand = NULL
+) {
   img_path <- file.path("img", path)
   screen_width <- 1920
   screen_height <- 1080
@@ -27,31 +30,41 @@ screen_height <- 1080
 b <- ChromoteSession$new(height = screen_height, width = screen_width)
 
 # Landing page ----
-p <- b$Page$loadEventFired(wait_ = FALSE)  # Get the promise for the loadEventFired
+p <- b$Page$loadEventFired(wait_ = FALSE) # Get the promise for the loadEventFired
 b$Page$navigate("https://r-universe.dev/search/")
 b$wait_for(p)
 screenshot(b, "search.png")
 
 # Searching for something ----
 screenshot_search <- function(query, screen_width) {
   message(query)
-  p <- b$Page$loadEventFired(wait_ = FALSE)  # Get the promise for the loadEventFired
+  p <- b$Page$loadEventFired(wait_ = FALSE) # Get the promise for the loadEventFired
   b$Page$navigate(sprintf("https://r-universe.dev/search/?q=%s", query))
   b$wait_for(p)
+  filename <- snakecase::to_lower_camel_case(query)
+
   screenshot(
-    b, sprintf("search-%s.png", snakecase::to_lower_camel_case(query))
+    b,
+    sprintf("search-%s.png", filename)
   )
 }
 purrr::walk(
-  c('"missing-data"', "author:jeroen json", "exports:toJSON"),
+  c(
+    '"missing-data"',
+    "author:jeroen json",
+    "exports:toJSON"
+  ),
   screenshot_search,
   screen_width = screen_width
 )
 # Searching, advanced fields ----
-p <- b$Page$loadEventFired(wait_ = FALSE)  # Get the promise for the loadEventFired
+p <- b$Page$loadEventFired(wait_ = FALSE) # Get the promise for the loadEventFired
 b$Page$navigate("https://r-universe.dev/search/")
 b$wait_for(p)
-search_info <- b$DOM$querySelector(b$DOM$getDocument()$root$nodeId, "button.btn.btn-outline-secondary.dropdown-toggle.dropdown-toggle-split")
+search_info <- b$DOM$querySelector(
+  b$DOM$getDocument()$root$nodeId,
+  "button.btn.btn-outline-secondary.dropdown-toggle.dropdown-toggle-split"
+)
 quads <- b$DOM$getBoxModel(search_info$nodeId)
 content_quad <- as.numeric(quads$model$content)
 center_x <- mean(content_quad[c(1, 3, 5, 7)])
@@ -77,12 +90,15 @@ b$Input$dispatchMouseEvent(
 )
 Sys.sleep(2)
 screenshot(
-  b, "search-advanced.png", selector = "#searchbox", expand = 20
+  b,
+  "search-advanced.png",
+  selector = "#searchbox",
+  expand = 20
 )
 
 # work from an organization ----
 screenshot_org <- function(tab, url) {
-  p <- b$Page$loadEventFired(wait_ = FALSE)  # Get the promise for the loadEventFired
+  p <- b$Page$loadEventFired(wait_ = FALSE) # Get the promise for the loadEventFired
   b$Page$navigate(sprintf("%s/%s/", url, tab))
   #if (tab == "contributors") Sys.sleep(20)
   b$wait_for(p)
@@ -98,7 +114,7 @@ purrr::walk(
 pkg_url <- "https://r-spatial.r-universe.dev/sf"
 fragments <- c("", "citation", "development", "readme", "manual")
 screenshot_pkg <- function(fragment, pkg_url) {
-  p <- b$Page$loadEventFired(wait_ = FALSE)  # Get the promise for the loadEventFired
+  p <- b$Page$loadEventFired(wait_ = FALSE) # Get the promise for the loadEventFired
   b$Page$navigate(pkg_url)
   b$wait_for(p)
 
@@ -116,9 +132,13 @@ screenshot_pkg <- function(fragment, pkg_url) {
     b,
     sprintf("pkg-%s.png", fragment),
     # https://github.com/rstudio/chromote/issues/168
-    cliprect = c(top = 0, left = quads$model$margin[[2]], width = 1920, height = 1080)
+    cliprect = c(
+      top = 0,
+      left = quads$model$margin[[2]],
+      width = 1920,
+      height = 1080
+    )
   )
-
 }
 purrr::walk(fragments, screenshot_pkg, pkg_url = pkg_url)
 
@@ -133,5 +153,10 @@ screenshot(
   b,
   "pkg-function-doc.png",
   # are top and left inverted? it seems so!
-  cliprect = c(top = 0, left = quads$model$margin[[2]], width = 1920, height = 1080)
+  cliprect = c(
+    top = 0,
+    left = quads$model$margin[[2]],
+    width = 1920,
+    height = 1080
+  )
 )

browse/api.qmd

@@ -158,7 +158,7 @@ deps$total
 ```
 
 
-## Search all universes
+## Search all universes {#api-global-search}
 
 URL: `https://r-universe.dev/api/search`
 Parameters:

browse/search.qmd

@@ -3,11 +3,25 @@ title: "Search for packages"
 ---
 
 You can search for packages via <https://r-universe.dev/search/> using keywords or author names.  
-To search for an exact phrase like "weather data," use **double quotes** instead of single quotes.  
-The search bar includes a drop-down button for accessing advanced search fields. 
+You can use the [API](#api-global-search) to do the same search.
+
+To search for an exact phrase like "weather data", that can include spaces or other characters, use **double quotes** instead of single quotes.  
+
 
 ![Search landing page](../img/search.png){group="search" fig-alt="Search landing page, with a search box"}
 
+The search bar includes a drop-down button for accessing advanced search fields:
+
+- Package
+- Owner
+- Author
+- Contributor
+- Topic
+- Needs
+- Exports
+- Data
+
+
 ![Search landing page, advanced fields](../img/search-advanced.png){group="search" fig-alt="Search landing page, displaying advanced search fields like author and keywords"}
 
 ![Search results for '"missing-data"'](../img/search-missingData.png){group="search" fig-alt="Search results for 'missing-data'"}
@@ -16,6 +30,13 @@ The search bar includes a drop-down button for accessing advanced search fields.
 
 ![Search results for 'exports:toJSON'](../img/search-exportsToJson.png){group="search" fig-alt="Search results for 'exports:tojson'"}
 
+To use a logical OR, add a space between search terms. [Example](https://r-universe.dev/search?q=jeroen%20curl).
+
+To use a logical AND, use double quotes for each search term. [Example](https://r-universe.dev/search?q=%22jeroen%22%20%22curl%22).
+
+To use a logical NOT: prefix search terms with -. [Example](https://r-universe.dev/search?q=jeroen%20-curl%20-json).
+
+
 ## How is the package-rank score calculated? {#rank}
 
 The rank of a package in search results is based on its [match](https://github.com/r-universe-org/cranlike-server/blob/master/src/db.js#L63-L93) with the search queries, and on its popularity/quality.