Document in one place

DESCRIPTION

@@ -32,6 +32,7 @@ Suggests:
     styler (>= 1.2),
     testthat,
     tic,
+    versions,
     yaml
 VignetteBuilder: 
     knitr

tests/testthat.R

@@ -1,4 +1,10 @@
 library(testthat)
 library(precommit)
+versions <- versions::available.versions("desc")
+
+
+if (max(as.package_version(versions$desc$version)) > "1.2") {
+  rlang::abort("newer version of desc on CRAN. Adapt the warning and maybe add minimal version requirement?")
+}
 
 test_check("precommit")

vignettes/available-hooks.Rmd

@@ -1,49 +1,182 @@
 ---
-title: "Available hooks"
+title: "Available Hooks"
 output: rmarkdown::html_vignette
 vignette: >
   %\VignetteIndexEntry{available-hooks}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
 
-This repo contains a collection of git pre-commit hooks to use with
-[pre-commit.com](https://pre-commit.com). Currently, this repo hosts:
+Below is a comprehensive list with all hooks from {precommit} as well well as
+their arguments or flags, if they take any. Other repos also host hooks, many
+are listed [here](https://pre-commit.com/hooks.html).
 
-* `style-files`: A hook to style files with [styler](https://styler.r-lib.org).
-  Only commit code corresponding to the tidyverse style guide. To customize, see
-  `vignette("available-hooks")`.
+# File modification
 
-* `readme-rmd-rendered`: Make sure `README.Rmd` hasn't been edited more recently
-  than `README.md`, i.e. remind you to render the `.Rmd` to `.md` before
-  committing.
+Some hooks will fail without changing the files you want to commit, like the
+`lintr` hook - and you need to make manual changes for the hook to pass on the
+next attempt. Other hooks like the `styler` hook write to files, and if that
+changes the file, the hook will fail, but this means you won't need to modify
+the file manually, just stage the changes and try to commit again. Below, we
+indicate for every hook if it modifies files or not.
 
-* `parsable-R`: Checks if your `.R` files are "valid" R code.
+# Arguments 
 
-* `no-browser-statement`: Guarantees you that you don't accidentally commit code
-  with a `browser()` statement in it.
+Arguments are specified as described in the [pre-commit.com
+documentation](https://pre-commit.com/#passing-arguments-to-hooks), e.g. we can
+set the argument `style_pkg` to `styler` and `style_fun` to `tidyverse_style`
+for the hook `style-files` like this:
 
-* `spell-check`: Checks spelling with `spelling::spell_check_files()`. Excluded
-  are R and python scripts as well as .gitignore. To customize, see the vignette
-  *Hook arguments*.
+```{r, echo = FALSE, output = "asis", comment = "", message = FALSE}
+library(magrittr)
+config <- yaml::read_yaml(system.file("pre-commit-config.yaml", package = "precommit", mustWork = TRUE))
+rev <- purrr::imap(config$repos, function(x, y) {
+  if (x$repo == "https://github.com/lorenzwalthert/precommit") {
+    return(x$rev)
+  }
+}) %>%
+  purrr::compact() %>%
+  unlist()
+cat(glue::glue("
+repos:
+-   repo: https://github.com/lorenzwalthert/precommit
+    rev: {rev}
+    hooks:
+    -   id: style-files
+        args: [--style_pkg=styler, --style_fun=tidyverse_style]
+"))
+```
 
-* `roxygenize`: A hook to run `roxygen2::roxygenize()`. Makes sure you commit
-  your `.Rd` changes with the source changes.
+# Hooks
 
-* `deps-in-desc`: Checks if packages used with the `pkgname::fun()` syntax are
-  listed in your DESCRIPTION file.
+## `style-files`
 
-* `use-tidy-description`: A hook to run `usethis::use_tidy_description()` to
-  ensure dependencies are ordered alphabetically and fields are in standard
-  order.
+A hook to style files with [styler](https://styler.r-lib.org). Only commit code
+corresponding to the tidyverse style guide. Set argument `style_pkg` and
+`style_fun` if you want to use another style guide than the tidyverse style
+guide.
 
-* `lintr`: A hook to run `lintr::lint()` to check that R files are lint free.
+```
+  id: style-files
+  args: [--style_pkg=<styler>, --style_fun=<tidyverse_style>]
+```
 
-* `codemeta-description-updated`: Make sure `DESCRIPTION` hasn't been edited
-  more recently than `codemeta.json`, i.e. remind you to run
-  `codemetar::write_codemeta()` in order to keep `codemeta.json` in sync with
-  `DESCRIPTION`.
+This hook modifies files.
 
-Other repos also host hooks, many are listed
-[here](https://pre-commit.com/hooks.html).
+## `readme-rmd-rendered`
+
+Make sure `README.Rmd` hasn't been edited more recently than `README.md`, i.e.
+remind you to render the `.Rmd` to `.md` before committing.
+
+This hook does not modify files.
+
+## `parsable-R`
+
+Checks if your `.R` files are "valid" R code by checking if running `parse()` on
+it returns an error.
+
+This hook does not modify files.
+
+## `no-browser-statement`
+
+Guarantees you that you don't accidentally commit code with a `browser()`
+statement in it.
+
+This hook does not modify files.
+
+## `spell-check`
+
+Checks spelling with `spelling::spell_check_files()`. Excluded are R and python
+scripts as well as `.gitignore` and similar. To be precise, files matching the
+following regex are excluded by default (as of `r paste0("v",
+desc::desc_get_version())`):
+
+```{r, echo = FALSE, comment = ""}
+extract_spell_check_regex <- function() {
+  yaml::read_yaml(here::here(".pre-commit-hooks.yaml")) %>%
+    purrr::keep(~ .x$id == "spell-check") %>%
+    magrittr::extract2(1) %>%
+    magrittr::extract2("exclude")
+}
+
+cat(extract_spell_check_regex())
+```
+
+Argument `ignore_files` takes a regular expression matched with `base::grep()`
+to ignore further files from the hook. Argument `lang` is passed to
+`spelling::spell_check_files()`.
+
+```
+id: spell-check
+args: [--ignore_files=<ignored_files>, --lang=<language>]
+```
+
+This hook does not modify files. It will add all words not found in the
+dictionary to `inst/WORDLIST`, assuming they were spelled correctly but were not
+in the dictionary. An example might be "RStudio". The hook error message will
+contain all words written to `inst/WORDLIST`, so if there were really some
+typos, make sure to fix them and remove them from `inst/WORDLIST`. If there were
+not typos, or you fixed all, stage `inst/WORDLIST` and this time, the commit
+should pass.
+
+## `roxygenize`
+
+A hook to run `roxygen2::roxygenize()`. Makes sure you commit your `.Rd` changes
+with the source changes.
+
+This hook modifies files.
+
+## `deps-in-desc`
+
+Checks if packages used with the `pkgname::fun()` syntax are listed in your
+DESCRIPTION file. Flag `allow_private_imports` lets the user specify that
+private imports into the package namespace are tolerable, e.g. `somepkg:::x()`.
+Flag not set by default, i.e. the hook will fail if such a call is found.
+
+```
+id: deps-in-desc args: [--allow_private_imports] 
+```
+
+This hook does not modify the file `DESCRIPTION` because the user should decide
+for each package if it should go to `Imports:` or `Suggests:`, which can be done
+easily with `usethis::use_package()`. For those who use
+`usethis::use_package()`: As long as the CRAN version of the dependency {desc}
+is `v1.2.0`, we recommend you to install the GitHub version because otherwise,
+the new dependencies won't be added in alphabetical order and after adding a
+dependency, `use-tidy-description` will fail in most cases
+(#85)[https://github.com/r-lib/desc/pull/85].
+
+## `use-tidy-description`
+
+A hook to run `usethis::use_tidy_description()` to ensure dependencies are
+ordered alphabetically and fields are in standard order.
+
+This hook does modify the file `DESCRIPTION`.
+
+## `lintr`
+
+A hook to run `lintr::lint()` to check that R files are lint free. Argument
+`warning_only` changes the behavior of the pre-commit to be non-blocking. You
+should set this with the field `verbose: true`.
+
+```
+id: lintr
+args: [--warn_only]
+verbose: true
+```
+
+When configured this way, lintr prints lint errors as they appear. Other
+arguments are not supported. Instead, `lintr` config should be specified in a
+`.lintr` config file in Debian Control Field Format as specified in the
+[`.lintr` documentation](https://github.com/jimhester/lintr#project-configuration).
+
+This hook does not modify any file.
+
+## `codemeta-description-updated`
+
+Make sure `DESCRIPTION` hasn't been edited more recently than `codemeta.json`,
+i.e. remind you to run `codemetar::write_codemeta()` in order to keep
+`codemeta.json` in sync with `DESCRIPTION`.
+
+This hook does not modify any file.
 

vignettes/manual-installation.Rmd

@@ -87,7 +87,7 @@ cat(string)
 The `repo` key points to the place where the source code of the hooks are
 stored, not the repo you want to apply them to.
 
-Some hooks also take arguments, see `vignette("hook-arguments")`.
+Some hooks also take arguments, see `vignette("available-hooks")`.
 
 If you want to see the file `.pre-commit-config.yaml` in RStudio, you have to
 enable "Show Hidden Files" in the *Files* Pane of RStudio under *More*.