docs: create a new vignette for advanced features (#34)

* create new vignette

* update docs

* fix pkgdown index

* reference vignette in docs

* Update vignettes/advanced-usage.Rmd

---------

R/api.R

@@ -23,7 +23,10 @@
 #'
 #' @returns
 #' `s()` returns a `selenider_element` object.
-#' `ss()` returns a `selenider_elements` object.
+#' `ss()` returns a `selenider_elements` object. Note that this is not a list,
+#' and you should be careful with the functions that you use with it. See the
+#' advanced usage vignette for more details:
+#' `vignette("advanced-usage", package = "selenider")`.
 #'
 #' @seealso
 #' * [find_element()] and [find_elements()]

R/cache.R

@@ -38,8 +38,8 @@
 #'
 #' @seealso
 #' * [find_element()] and [find_elements()] to select elements.
-#' * [element_list()], [find_each_element()] and [find_all_elements()] if you
-#'   want to iterate over an element collection.
+#' * [as.list.selenider_elements()], [find_each_element()] and
+#'   [find_all_elements()] if you want to iterate over an element collection.
 #'
 #' @examplesIf selenider::selenider_available(online = FALSE)
 #' html <- "

R/elem_filter.R

@@ -35,7 +35,7 @@
 #'
 #' @seealso
 #' * [find_elements()] and [ss()] to get elements to filter.
-#' * [is_present()] and other conditions for predicates for HTML elements.
+#' * [is_present()] and other conditions for predicates on HTML elements.
 #'   (If you scroll down to the *See also* section, you will find the rest).
 #'
 #' @examplesIf selenider::selenider_available(online = FALSE)

R/find_elements.R

@@ -16,15 +16,20 @@
 #' `xpath`), the first element which satisfies every condition will be found.
 #'
 #' @returns
-#' A `selenider_elements` object.
+#' A `selenider_elements` object. Note that this is not a list, and you should
+#' be careful with the functions that you use with it. See the advanced usage
+#' vignette for more details:
+#' `vignette("advanced-usage", package = "selenider")`.
 #'
 #' @seealso
 #' * [ss()] to quickly select multiple elements without specifying the session.
-#' * [find_element()] to select multiple elements.
+#' * [find_element()] to select a single element.
 #' * [selenider_session()] to begin a session.
 #' * [elem_children()] and family to select elements using their relative
 #'   position in the DOM.
 #' * [elem_filter()] and [elem_find()] for filtering element collections.
+#' * [as.list.selenider_elements()] to convert a `selenider_elements` object
+#'   to a list.
 #'
 #' @examplesIf selenider::selenider_available(online = FALSE)
 #' html <- "

R/get_actual_element.R

@@ -25,7 +25,7 @@
 #' * [s()], [ss()], [find_element()] and [find_elements()] to select selenider
 #'   elements.
 #' * [elem_cache()] and [elem_cache()] to cache these values.
-#' * The [Chrome Devtools Protocol documentation](https://chromedevtools.github.io/devtools-protocol/tot/) `r # nolint`
+#' * The [Chrome Devtools Protocol documentation](https://chromedevtools.github.io/devtools-protocol/tot/)
 #'   for the operations that can be performed using a backend node id. Note
 #'   that this requires the [chromote::ChromoteSession] object, which can be
 #'   retrieved using `<selenider_session>$driver`.

R/session-options.R

@@ -61,7 +61,8 @@ chromote_options <- function(headless = TRUE,
 #' @rdname chromote_options
 #'
 #' @param client_options A [selenium_client_options()] object.
-#' @param server_options A [selenium_server_options()] object.
+#' @param server_options A [selenium_server_options()] object, or `NULL` if you
+#'   don't want one to be created.
 #'
 #' @export
 selenium_options <- function(client_options = selenium_client_options(),

README.md

@@ -1,4 +1,3 @@
-
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
 # selenider
@@ -10,6 +9,7 @@
 coverage](https://codecov.io/gh/ashbythorpe/selenider/branch/main/graph/badge.svg)](https://app.codecov.io/gh/ashbythorpe/selenider?branch=main)
 [![CRAN
 status](https://www.r-pkg.org/badges/version/selenider)](https://CRAN.R-project.org/package=selenider)
+
 <!-- badges: end -->
 
 Traditionally, automating a web browser is often unreliable, especially
@@ -59,7 +59,7 @@ concise yet expressive code that is easy to read and easy to write:
 
 ## Installation
 
-``` r
+```r
 # Install selenider from CRAN
 install.packages("selenider")
 
@@ -73,7 +73,7 @@ Additionally, you must install
 [selenium](https://ashbythorpe.github.io/selenium-r/). We recommend
 chromote, as it is quicker and easier to get up and running.
 
-``` r
+```r
 # Either:
 install.packages("chromote")
 
@@ -91,15 +91,15 @@ is recommended.
 
 ## Usage
 
-``` r
+```r
 library(selenider)
 ```
 
 The following code navigates to the [R project
 website](https://www.r-project.org/), finds the link to the CRAN mirror
 list, checks that the link is correct, and clicks the link element.
 
-``` r
+```r
 open_url("https://www.r-project.org/")
 
 s(".row") |>
@@ -113,25 +113,25 @@ s(".row") |>
 Now that we’re in the mirror list page, let’s find the link to every
 CRAN mirror in the UK.
 
-``` r
+```r
 s("dl") |>
   find_elements("dt") |>
   elem_find(has_text("UK")) |>
   find_element(xpath = "./following-sibling::dd") |>
   find_elements("tr") |>
+  find_each_element("a") |>
   elem_expect(has_at_least(1)) |>
   as.list() |>
   lapply(
     \(x) x |>
-      find_element("a") |>
       elem_attr("href")
   )
 #> [[1]]
 #> [1] "https://www.stats.bris.ac.uk/R/"
-#> 
+#>
 #> [[2]]
 #> [1] "https://cran.ma.imperial.ac.uk/"
-#> 
+#>
 #> [[3]]
 #> [1] "https://anorien.csc.warwick.ac.uk/CRAN/"
 ```

_pkgdown.yml

@@ -69,6 +69,7 @@ articles:
     contents:
       - unit-testing
       - with-rvest
+      - advanced-usage
   - title: Testing selenider
     desc: An article used to test selenider
     contents: