Merge branch 'cran-release'

Author: statnmap

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: gitdown
 Title: Turn Your Git Commit Messages into a HTML Book
-Version: 0.1.0
+Version: 0.1.1
 Authors@R: 
     c(person(given = "Sébastien",
              family = "Rochette",
@@ -22,7 +22,8 @@ Description: Read all commit messages of your local git repository and
     organisms required to testify for every changes in their source code,
     in relation to features requests.
 License: MIT + file LICENSE
-URL: https://github.com/Thinkr-open/gitdown
+URL: https://thinkr-open.github.io/gitdown/,
+    https://github.com/Thinkr-open/gitdown
 BugReports: https://github.com/Thinkr-open/gitdown/issues
 Depends: 
     R (>= 3.4)
@@ -45,4 +46,5 @@ Suggests:
 VignetteBuilder: 
     knitr
 Encoding: UTF-8
+Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.1.1

NEWS.md

@@ -1,3 +1,7 @@
+# gitdown 0.1.1
+
+* Improve documentation
+
 # gitdown 0.1.0
 
 * Get ready for CRAN

R/fake_repo.R

@@ -9,8 +9,8 @@
 #' @importFrom git2r init config add commit tag
 #' @export
 #'
-#' @return A few files and an initiated git repository in 'path'.
-#' Returns the path of the fake repository.
+#' @return Character. Path of a fake repository used for reproducible examples.
+#' Fake repository contains a few files with an initiated git repository.
 #' @examples
 #' # Fake repository with git
 #' fake_repo()

R/get_commits.R

@@ -3,7 +3,17 @@
 #' @inheritParams git2r::commits
 #' @param silent Logical. Whether to hide messages.
 #'
-#' @return A tibble with commits content, information and associated tags
+#' @return A tibble with one line for each commit and the following columns:
+#'
+#' - sha: sha of the commit
+#' - summary: First line of the commit message
+#' - message: Full content of the commit message
+#' - author: author of the commit
+#' - email: email of the author
+#' - when: commit time
+#' - order: order of commit messages. 1 is the oldest.
+#' - tag.name: name of tag associated with all commits since the last tag
+#' - tag.message: message of the tagged commit
 #'
 #' @importFrom git2r commits tags
 #' @importFrom purrr map_dfr flatten
@@ -61,13 +71,26 @@ get_commits_tags <- function(repo = ".", ref = "master",
 
 #' Get commits associated with a text pattern
 #'
-#' @param pattern Named vector with regex pattern to expose commits, like c("Issues" = "#[[:digit:]]") for issues
-#' @param pattern.table data.frame with two columns: pattern and description.
+#' @param pattern Named vector with regex pattern to expose commits, like `c("Issues" = "#\[\[:digit:\]\]")` for issues
+#' @param pattern.table data.frame with two columns: pattern and description of the pattern.
 #' This is used as correspondence table to add some names to existing patterns.
 #' @inheritParams git2r::commits
 #' @inheritParams get_commits_tags
 #'
-#' @return A tibble with commits content, information, associated tags and associated patterns found.
+#' @return A tibble with one line for each commit, duplicated if
+#'  associated with multiple patterns and the following columns:
+#'
+#' - sha: sha of the commit
+#' - summary: First line of the commit message
+#' - message: Full content of the commit message
+#' - author: author of the commit
+#' - email: email of the author
+#' - when: commit time
+#' - order: order of commit messages. 1 is the oldest.
+#' - tag.name: name of tag associated with all commits since the last tag
+#' - tag.message: message of the tagged commit
+#' - pattern.type: name of the pattern found in the commit message
+#' - pattern.content: pattern found in the commit message
 #'
 #' @importFrom dplyr mutate distinct rowwise tibble left_join mutate
 #' @importFrom dplyr if_else mutate_all filter select
@@ -150,6 +173,7 @@ get_commits_pattern <- function(repo = ".", pattern = c("Ticket" = "#[[:digit:]]
 #' @inheritParams stringi::stri_extract_all
 #'
 #' @importFrom stringi stri_extract_all
+#' @noRd
 
 my_extract <- function(message, pattern) {
   # res <- unlist(str_extract_all(message, pattern, simplify = FALSE))

R/get_info_files.R

@@ -3,6 +3,7 @@
 #' @param object hunks list
 #'
 #' @return time
+#' @noRd
 get_time <- function(object) {
   pluck(object, "final_signature", "when", "time")
 }
@@ -12,7 +13,16 @@ get_time <- function(object) {
 #' @param path path to the file
 #' @param repo repo of the git project
 #'
-#' @return A list with information on first and last modification time of the selected file.
+#' @return A list with information of the selected file:
+#'
+#' - file: file name
+#' - in_repository: Logical. Whether the file has already been commit once in the
+#' git repository
+#' - first_modif: time of first modification. Commit time if in the git repository,
+#' system date of creation otherwise.
+#' - last_modif: time of last modification. Commit time if in the git repository,
+#' system date of last modification otherwise.
+#'
 #' @export
 #'
 #' @importFrom git2r blame
@@ -61,14 +71,23 @@ get_info <- function(path, repo = ".") {
   )
 }
 
-#' Get the first and last modification time of files of a repository
+#' Get the first and last modification time of files of a directory
 #'
 #' @param repo git repository
-#' @param path Default to R folder. Use "" for the complete repository.
+#' @param path Default to R folder. Use "" for the complete directory
 #' @param recursive Logical. Should the listing recurse into directories?
 #' @param untracked Logical. Should the not tracked files be included?
 #'
-#' @return A list of files with information on first and last modification time.
+#' @return A list of files with information of each file:
+#'
+#' - file: file name
+#' - in_repository: Logical. Whether the file has already been commit once in the
+#' git repository
+#' - first_modif: time of first modification. Commit time if in the git repository,
+#' system date of creation otherwise.
+#' - last_modif: time of last modification. Commit time if in the git repository,
+#' system date of last modification otherwise.
+#'
 #' @export
 #'
 #' @importFrom purrr map
@@ -147,7 +166,8 @@ present_files <- function(repo = ".", path = "R",
 
 #' Creates and updates a vignette in the 'vignette/' directory of a package with last modification time of tracked files
 #'
-#' @return Creates and updates the content of the "modification_files.Rmd" vignette
+#' @return No return value, called for side effect.
+#' Creates and updates the content of the "modification_files.Rmd" vignette
 #' @export
 #'
 #' @rdname create_vignette_last_modif

R/git_down.R

@@ -1,4 +1,4 @@
-#' Turns the history of git into a bookdown.
+#' Turns the active branch history of git into a bookdown.
 #'
 #' Read all commit messages of your local git repository and
 #' sort them according to tags or specific text pattern into chapters of
@@ -10,12 +10,12 @@
 #' @param open Should the bookdown be opened once compiled? Default is TRUE.
 #' @param author Author of the bookdown
 #' @param ref the name of the branch, by default master
-#' @param ... Other parameters to pass to \code{\link[rmarkdown]{render}}
+#' @param ... Other parameters to pass to [rmarkdown::render()]
 #'
 #' @inheritParams get_commits_pattern
 #' @export
 #'
-#' @return A directory with content of a HTML gitbook
+#' @return Path of the HTML gitbook saved in the repo/book_path directory.
 #'
 #' @importFrom attempt if_not
 #' @importFrom rmarkdown render
@@ -28,17 +28,20 @@
 #' repo <- fake_repo()
 #' res <- git_down(repo, pattern = c("Tickets" = "ticket[[:digit:]]+", "Issues" = "#[[:digit:]]+"),
 #' open = FALSE)
+#' \dontrun{
 #' # Open the book
-#' # browseURL(res)
-#'
+#'   browseURL(res)
+#' }
 #' # With table of correspondence
 #' pattern.table <- data.frame(number = c("#2", "#1"),
 #'   title = c("#2 A second issue to illustrate a blog post",
 #'                        "#1 An example of issue"))
 #' res <- git_down(repo, pattern = c("Issues" = "#[[:digit:]]+"),
 #'   pattern.table = pattern.table, open = FALSE)
+#' \dontrun{
 #' # Open the book
-#' # browseURL(res)
+#'   browseURL(res)
+#' }
 
 git_down <- function(repo = ".", book_path = "gitdown",
                      open = TRUE, author = "John Doe",

R/gitdown-package.R

@@ -0,0 +1,15 @@
+#' @description Read all commit messages of your local git repository
+#' and sort them according to tags or specific text pattern into chapters
+#'  of a HTML book using 'bookdown'.
+#'  The git history book presentation helps organisms required to testify
+#'  for every changes in their source code, in relation to features requests.
+#'
+#'  The main functions to be used in this package are [git_down()] and [create_vignette_last_modif()]
+#' @keywords internal
+"_PACKAGE"
+
+# The following block is used by usethis to automatically manage
+# roxygen namespace tags. Modify with care!
+## usethis namespace: start
+## usethis namespace: end
+NULL

R/utils-pipe.R

@@ -1,11 +1,14 @@
 #' Pipe operator
 #'
-#' See \code{magrittr::\link[magrittr:pipe]{\%>\%}} for details.
+#' See `magrittr::[\%>\%][magrittr::pipe]` for details.
 #'
 #' @name %>%
 #' @rdname pipe
 #' @keywords internal
 #' @export
 #' @importFrom magrittr %>%
 #' @usage lhs \%>\% rhs
+#' @param lhs A value or the magrittr placeholder.
+#' @param rhs A function call using the magrittr semantics.
+#' @return The result of calling `rhs(lhs)`.
 NULL

R/utils.R

@@ -3,7 +3,7 @@
 #' @param file Path of file
 #' @param pattern Pattern to replace
 #' @param replacement A character vector of replacements
-#'
+#' @noRd
 replace_in_file <- function(file, pattern, replacement) {
   a <- readLines(file)
   a <- gsub(pattern, replacement, a)
@@ -16,7 +16,7 @@ replace_in_file <- function(file, pattern, replacement) {
 #' @param dir Name of the dir where to write file
 #' @param rmd name and type of the file to write in
 #' @param repo Path to directory where to store "dir"
-#'
+#' @noRd
 write_in <- function(x, repo, dir =  "gitdown", rmd = "index.Rmd") {
   dir_out <- normalizePath(file.path(repo, dir))
   if (!dir.exists(dir_out)) {dir.create(dir_out)}
@@ -27,6 +27,7 @@ write_in <- function(x, repo, dir =  "gitdown", rmd = "index.Rmd") {
 #' Presentation of commit
 #'
 #' @param commit one line data from get_commits_pattern
+#' @noRd
 
 presentation_commit <- function(commit) {
   res <- paste0(
@@ -65,6 +66,7 @@ presentation_commit <- function(commit) {
 #'
 #' @importFrom purrr map_chr
 #'
+#' @noRd
 
 each_commit <- function(commits, pattern.content, link_pattern, pattern.type, pattern.title) {
   # if no commits
@@ -89,6 +91,7 @@ each_commit <- function(commits, pattern.content, link_pattern, pattern.type, pa
 
 #' To singular
 #' @param x Character
+#' @noRd
 to_singular <- function(x) {
   gsub("s$", "", x)
 }
@@ -101,13 +104,32 @@ to_singular <- function(x) {
 #' @importFrom stringi stri_extract_all
 #' @importFrom tidyr nest
 #'
-#' @return A tibble with a row for each different pattern found and
+#' @return A tibble with a row for each different pattern found in commit messages
+#' and following columns:
+#'
+#' - pattern.type: name of the pattern found in the commit message
+#' - pattern.content: pattern found in the commit message
+#' - pattern.title: pattern.content or title used in the pattern.table
 #' a nested 'data' column with all related commits
+#' - pattern_numeric: extraction of numeric value in pattern.content
+#' - link_pattern: internal url of the pattern in the future HTML gitbook
+#' - data: a nested list of tibbles with commits content as issued from [get_commits_pattern()]
 #'
 #' @export
 #' @examples
 #' repo <- fake_repo()
 #' nest_commits_by_pattern(repo)
+#'
+#' # With table of correspondence
+#' pattern.table <- data.frame(
+#'   number = c("#2", "#1", "#1000"),
+#'   title = c("#2 A second issue to illustrate a blog post",
+#'             "#1 An example of issue",
+#'             "#1000 issue with no commit"))
+#'  nest_commits_by_pattern(
+#'   repo,
+#'   pattern.table = pattern.table,
+#'   pattern = c("Tickets" = "ticket[[:digit:]]+", "Issues" = "#[[:digit:]]+"))
 
 nest_commits_by_pattern <- function(repo,
                                     pattern = c("Issues" = "#[[:digit:]]+"),
@@ -172,7 +194,18 @@ nest_commits_by_pattern <- function(repo,
 #' @importFrom purrr map_chr pmap
 #' @export
 #' @return A tibble with a row for each different pattern found and
-#' a 'text' column to be included in a markdown file.
+#' a 'text' column to be included in a markdown file:
+#'
+#' - pattern.content: pattern found in the commit message
+#' - link_pattern: internal url of the pattern in the future HTML gitbook
+#' - text: list of vectors of markdown text to present commits of each pattern
+#' in the HTML gitbook output
+#' - pattern.type: name of the pattern found in the commit message
+#' - pattern.title: pattern.content or title used in the pattern.table
+#' a nested 'data' column with all related commits
+#' - pattern_numeric: extraction of numeric value in pattern.content
+#' - data: a nested list of tibbles with commits content as issued from [get_commits_pattern()]
+#'
 #' @examples
 #' repo <- fake_repo()
 #' res_commits <- nest_commits_by_pattern(
@@ -233,6 +266,7 @@ each_pattern <- function(nest_commits, pattern.type) {
 
 #' Clean link
 #' @param x Character to clean to transform as slug
+#' @noRd
 
 clean_link <- function(x) {
   x %>%
@@ -250,6 +284,7 @@ clean_link <- function(x) {
 #'
 #' Removes stars, underscores, \{\} and []
 #' @param x Character to clean to transform as slug
+#' @noRd
 
 clean_text <- function(x) {
   x %>%