Improve documentation

Author: statnmap

DESCRIPTION

@@ -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

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

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

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,6 +1,6 @@
 #' Pipe operator
 #'
-#' See \code{magrittr::\link[magrittr:pipe]{\%>\%}} for details.
+#' See `magrittr::[\%>\%][magrittr::pipe]` for details.
 #'
 #' @name %>%
 #' @rdname pipe

R/utils.R

@@ -104,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:]]+"),
@@ -175,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(

README.Rmd

@@ -40,7 +40,13 @@ You can install the last version of {gitdown} from Github:
 remotes::install_github("ThinkR-open/gitdown")
 ```
 
-## Example
+## Create a reproducible example of a versioned directory
+
+Create a versioned directory with some commits and a NEWS.md in a temporary directory
+
+- Some commits mention an issue with `#`
+- Some commits mention a ticket with `ticket`
+- A commit is associated with a tag
 
 ```{r example, message=FALSE}
 library(dplyr)
@@ -49,26 +55,11 @@ library(gitdown)
 repo <- fake_repo()
 ```
 
-Get commits with issues mentioned. The searched pattern is a `#` followed by at least one number: `"#[[:digit:]]+"`. Variable `pattern.content` lists patterns found in the commit messages. 
-
-```{r}
-get_commits_pattern(repo, pattern = "#[[:digit:]]+", ref = "master") %>% 
-  select(pattern.content, everything())
-```
-
-Get commits with issues and specific home-made pattern. Use a named vector to properly separate types of patterns.
-
-```{r}
-get_commits_pattern(
-  repo, 
-  pattern =  c("Tickets" = "ticket[[:digit:]]+", "Issues" = "#[[:digit:]]+"),
-  ref = "master"
-) %>% 
-  select(pattern.type, pattern.content, everything())
-```
-
 ## Create a gitbook of commits sorted by a pattern
 
+The main function of {gitdown} is to build this gitbook with all commit messages ordered according to a pattern. Each commit message associated with an issue will be recorded in the section of this issue. A commit message can thus appears multiple times if it is associated with multiple issues.  
+If you have your own referencing system for tickets in an external software, you can also create the gitbook associated like using `ticket` as in the example below.
+
 ```{r, eval=FALSE}
 git_down(repo, pattern = c("Tickets" = "ticket[[:digit:]]+",
                            "Issues" = "#[[:digit:]]+"))
@@ -79,7 +70,8 @@ knitr::include_graphics("reference/figures/gitdown_links.png")
 ```
 
 If you add a table of correspondence, you can change titles of the patterns.  
-_Note that you can use [{gitlabr}](https://statnmap.github.io/gitlabr/) or [{gh}](https://gh.r-lib.org) to retrieve list of issues from Gitlab or Github respectively._  
+_Note that you can use [{gitlabr}](https://statnmap.github.io/gitlabr/) or [{gh}](https://gh.r-lib.org) to retrieve list of issues from Gitlab or Github respectively, as presented in ["Download Gitlab or Github issues and make a summary report of your commits"](https://rtask.thinkr.fr/download-gitlab-or-github-issues-and-make-a-summary-report-of-your-commits/)._  
+
 ```{r, eval=FALSE}
 # With table of correspondence
 pattern.table <- data.frame(
@@ -99,6 +91,29 @@ _Note that characters like `[`, `]`, `_` or `*` will be replaced by `-` in the t
 knitr::include_graphics("reference/figures/issues-with-title.png")
 ```
 
+## Read list of commits and extract information
+
+As a side effect of {gitdown}, you can get some intermediate information used to build the book with some exported functions.
+
+Get commits with issues mentioned. The searched pattern is a `#` followed by at least one number: `"#[[:digit:]]+"`. Variable `pattern.content` lists patterns found in the commit messages. 
+
+```{r}
+get_commits_pattern(repo, pattern = "#[[:digit:]]+", ref = "master") %>% 
+  select(pattern.content, everything())
+```
+
+Get commits with issues and specific home-made pattern. Use a named vector to properly separate types of patterns.
+
+```{r}
+get_commits_pattern(
+  repo, 
+  pattern =  c("Tickets" = "ticket[[:digit:]]+", "Issues" = "#[[:digit:]]+"),
+  ref = "master"
+) %>% 
+  select(pattern.type, pattern.content, everything())
+```
+
+
 ## Create a vignette that lists all files with date of modification
 
 ```{r, eval=FALSE}