change export names to rdoc_* & check

.Rbuildignore

@@ -1,2 +1,5 @@
+^\.travis\.yml$
 ^.*\.Rproj$
 ^\.Rproj\.user$
+^src/\.vscode$
+^cran-comments\.md$

DESCRIPTION

@@ -1,11 +1,13 @@
 Package: rdoc
 Type: Package
-Title: Print Colourised Rd Files in the Console.
+Title: Colourised R documentation
 Version: 0.1.0
 Author: person("Matthew", "de Queljoe", email = "[email protected]", role = c("aut", "cre")
 Maintainer: Matthew de Queljoe <[email protected]>
-Description: Extends tools::Rd2txt by adding text and colour formatting to Rd files 
-    for terminal or console output.
+Description: Extends `tools::Rd2txt` by adding customisable text and colour formatting to R documentation 
+    contents for terminal or console output. If used in a terminal, output will carried out via `file.show` 
+    otherwise contents will be printed in sections. Formatting is done via crayon<https://cran.r-project.org/web/packages/crayon/index.html>
+    and prettycode<https://cran.r-project.org/web/packages/prettycode/index.html>.
 License: GPL-3
 Encoding: UTF-8
 LazyData: true

NAMESPACE

@@ -1,14 +1,14 @@
 # Generated by roxygen2: do not edit by hand
 
-export(rd)
-export(rd_arguments)
-export(rd_details)
-export(rd_example)
-export(rd_examples)
-export(rd_question)
-export(rd_usage)
 export(rdoc)
+export(rdoc_arguments)
+export(rdoc_details)
+export(rdoc_examples)
+export(rdoc_question)
 export(rdoc_style)
+export(rdoc_usage)
+export(rm_rdoc)
+export(use_rdoc)
 import(cli)
 import(crayon)
 import(prettycode)

R/options.R

@@ -48,6 +48,9 @@ R_logo <- crayon::combine_styles("bold", "blue")
 #' rdoc_text_formats())}
 #' @param r_logo \R symbol
 #' @param pkg \pkg{pkg} formatting
+#' @param italic italic font
+#' @param bold bold font
+#' @param squotes single quotes
 #' @param email email
 #' @param url = NULL
 #' @param href = NULL

R/rdoc.R

@@ -28,13 +28,13 @@ rd_ <- function(which = NULL) {
   }
 }
 
-#' Colourised R documentation
+#' Colourised \R documentation
 #'
 #' Refer to colourised \R docs as terminal/console output. Provides a
-#' replacement for \code{help}. A number of common section accessors are also
+#' replacement for \code{help}. A number of common (substantive) section accessors are also
 #' provided.
-#' @family rd access
-#' @aliases rd
+#' @family rdoc access
+#' @aliases rdoc
 #' @param topic \code{character(1)}, help topic
 #' @param package \code{character(1)}, package of help topic. Defaults to
 #'   \code{NULL}
@@ -51,41 +51,46 @@ rd_ <- function(which = NULL) {
 #'
 #' @examples \dontrun{
 #'
-#' rd("rd")
-#' rd(grepl)
-#' rd_example("min")
-#' rd_usage(substr)
+#' rdoc("rdoc")
+#' rdoc_examples("min")
+#' rdoc_usage(substr)
 #'
 #' }
 #' @export
-rd <- rd_()
+rdoc <- rd_()
 
 
-#' @rdname rd
+#' @rdname rdoc
 #' @export
-rd_details <- rd_("details")
+rdoc_usage <- rd_("usage")
 
-#' @rdname rd
+#' @rdname rdoc
 #' @export
-rd_arguments <- rd_("arguments")
+rdoc_arguments <- rd_("arguments")
 
-#' @rdname rd
+#' @rdname rdoc
 #' @export
-rd_usage <- rd_("usage")
+rdoc_details <- rd_("details")
 
-#' @rdname rd
+#' @rdname rdoc
 #' @aliases rd_examples
 #' @export
-rd_example <- rd_("examples")
-
-#' @export
-rd_examples <- rd_example
+rdoc_examples <- rd_("examples")
 
-#' rd ?
-#' @inherit rd details
+#' Colourised \R documentation
+#'
+#' Refer to colourised \R docs as terminal/console output. Provides a
+#' replacement for \code{?}.
+#' @inherit rdoc details
+#' @inheritParams utils::`?`
 #' @importFrom utils ?
+#' @examples \dontrun{
+#'
+#' rdoc_question(lapply)
+#'
+#' }
 #' @export
-rd_question <- function(type, topic) {
+rdoc_question <- function(type, topic) {
   type <- substitute(type)
   topic <- substitute(topic)
 
@@ -112,27 +117,36 @@ rd_question <- function(type, topic) {
 #'
 #' rdoc replacements for \code{?} and \code{help}
 #'
+#' @family use_rdoc shim
+#' @aliases use_rdoc
 #' @details
-#' Calling \code{rdoc()} will override \code{utils::`?`} with \code{rd_question}
+#' Calling \code{use_rdoc()} will override \code{utils::`?`} with \code{rd_question}
 #' and \code{utils::help} with \code{rd}
-#' These replacements can be unset by calling \code{rdoc()} once more.
+#' These replacements can be unset by calling \code{rm_rdoc()}.
 #' @examples \dontrun{
 #'
-#' rdoc::rdoc()
+#' rdoc::use_rdoc()
 #' ?help
-#' rdoc::rdoc()
+#' rdoc::rm_rdoc()
 #' ?help
 #' }
 #'
 #' @export
-rdoc <- function(){
+use_rdoc <- function(){
 
-  if ("rdoc" %in% searchpaths()){
-    detach("rdoc")
+  if ("rdoc" %in% search())
     return(invisible(NULL))
-  }
 
   e <- new.env()
-  e$`?` <- rd_question
-  attach(e, name = "rdoc", warn.conflicts = FALSE)
+  e$`?` <- rdoc_question
+  e$help <- rdoc
+  base::attach(e, name = "rdoc", warn.conflicts = FALSE)
+}
+
+#' @rdname use_rdoc
+#' @export
+rm_rdoc <- function(){
+  if (!"rdoc" %in% search())
+    return(invisible(NULL))
+  base::detach("rdoc")
 }

README.md

@@ -4,13 +4,31 @@
 [![codecov](https://codecov.io/gh/mdequeljoe/rdoc/branch/master/graph/badge.svg)](https://codecov.io/gh/mdequeljoe/rdoc)
 [![lifecycle](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://www.tidyverse.org/lifecycle/#maturing)
 
-rdoc = `?` + `tools::Rd2txt` + [cli](https://github.com/r-lib/cli) + [crayon](https://github.com/r-lib/crayon) + [prettycode](https://github.com/r-lib/prettycode)
+rdoc = `help` + `tools::Rd2txt` + [cli](https://github.com/r-lib/cli) + [crayon](https://github.com/r-lib/crayon) + [prettycode](https://github.com/r-lib/prettycode)
 
-![](man/img/rd.png)
+![](man/img/rdoc.png)
+
+
+Whilst primarily intended for usage in a terminal, `rdoc` can also be used sensibly elsewhere (such as Rstudio) whereby the output will be printed by sections to avoid flooding it with too much text.
 
 ## install
 
 (work in progress)
 ```r
 devtools::install_github("mdequeljoe/rdoc")
 ```
+
+## replacing `help` and `?`
+
+`help` and `?` can be overridden via:
+
+```r
+rdoc::use_rdoc()
+```
+
+Returning to the base functions is possible with:
+
+```r
+rdoc::rm_rdoc()
+```
+