From 32aaaaa3a7f64340436bc6a1ac880d2c1eed85b5 Mon Sep 17 00:00:00 2001 From: Jimmy Briggs Date: Sat, 14 Sep 2024 16:13:33 -0400 Subject: [PATCH] docs: add man pages for new functions --- man/generate_news.Rd | 126 ++++++++++++++++++++++++++++++++++ man/use_github_action_news.Rd | 38 ++++++++++ 2 files changed, 164 insertions(+) create mode 100644 man/generate_news.Rd create mode 100644 man/use_github_action_news.Rd diff --git a/man/generate_news.Rd b/man/generate_news.Rd new file mode 100644 index 0000000..aff6341 --- /dev/null +++ b/man/generate_news.Rd @@ -0,0 +1,126 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/pkg_news.R +\name{generate_news} +\alias{generate_news} +\alias{generate_news_from_changelog} +\title{Generate \code{NEWS.md}} +\usage{ +generate_news(output_file = "NEWS.md", ...) + +generate_news_from_changelog( + input_file = "CHANGELOG.md", + output_file = "NEWS.md", + include_unreleased = TRUE, + remove_commits = TRUE, + version_pattern = "^\\\\[(Unreleased|\\\\d+\\\\.\\\\d+\\\\.\\\\d+(?:-\\\\w+)?)\\\\]", + ordered_groups = .ordered_groups, + skip_groups = NULL, + section_name_mapping = NULL, + verbose = TRUE, + overwrite = FALSE, + pkg_name = NULL, + pkg_version = NULL, + pkg_path = NULL +) +} +\arguments{ +\item{output_file}{Path to the output \code{NEWS.md} file.} + +\item{...}{Arguments passed on to \code{generate_news_from_changelog()} from +\code{generate_news()}.} + +\item{input_file}{Path to the \code{CHANGELOG.md} file.} + +\item{include_unreleased}{Logical indicating whether to include the +\verb{[Unreleased]} section (default: \code{TRUE}).} + +\item{remove_commits}{Logical indicating whether to remove commit hashes +and authors from the list items (default: \code{TRUE}).} + +\item{version_pattern}{Regular expression pattern to match version headers +(default: \verb{^\\\[(Unreleased|\\\\d+\\\\.\\\\d+\\\\.\\\\d+(?:-\\\\w+)?)\\\]}).} + +\item{ordered_groups}{Character vector specifying the ordered groups for +sections in the \code{NEWS.md} file (default: \code{.ordered_groups}). +The default order is based on the significance of the groups.} + +\item{skip_groups}{Character vector specifying the groups to skip when +generating the \code{NEWS.md} file (default: \code{NULL}).} + +\item{section_name_mapping}{Named character vector to map section names +to custom names in the \code{NEWS.md} file (default: \code{NULL}). +The names should match the group names in the \code{CHANGELOG.md} file.} + +\item{verbose}{Logical indicating whether to display messages (default: \code{TRUE}).} + +\item{overwrite}{Logical indicating whether to overwrite existing \code{NEWS.md} file (default: \code{FALSE}).} + +\item{pkg_name}{Package name (default: \code{NULL}). If \code{NULL}, reads from \code{DESCRIPTION}.} + +\item{pkg_version}{Package version (default: \code{NULL}). If \code{NULL}, reads from \code{DESCRIPTION}.} + +\item{pkg_path}{Path to the package directory containing \code{DESCRIPTION} (default: \code{NULL}).} +} +\value{ +Both functions invisibly return the generated \code{news_content} +as a character vector. +} +\description{ +These functions generate the R package's \code{NEWS.md} file. +} +\details{ +\itemize{ +\item \code{generate_news()}: Generates a \code{NEWS.md} file by calling +\code{generate_news_from_changelog()} with default settings, +and will default to a generic \code{NEWS.md} file if no \code{CHANGELOG.md} +file is found. +\item \code{generate_news_from_changelog()}: Generates a \code{NEWS.md} file from a +pre-existing \code{CHANGELOG.md} file. It parses the Markdown content of +the \code{CHANGELOG.md} file, extracts version headers, sections, and their +content, and organizes them into a structured format suitable for +a typical R package's \code{NEWS.md} file. +} +} +\examples{ +if (interactive()) { + +# Examples of using the `generate_news()` function: +generate_news() + +# Examples of using the `generate_news_from_changelog()` function: + +# Generate NEWS.md from CHANGELOG.md using all default settings +generate_news_from_changelog() + +# Specify custom input and output files +generate_news_from_changelog( + input_file = "path/to/your/CHANGELOG.md", + output_file = "path/to/your/NEWS.md" +) + +# Overwrite the existing NEWS.md file +generate_news_from_changelog(overwrite = TRUE) + +# Exclude the 'Unreleased' section and keep commit hashes in the list items +generate_news_from_changelog(include_unreleased = FALSE, remove_commits = FALSE) + +# Skip certain sections +generate_news_from_changelog(skip_groups = c("Miscellaneous Tasks", "Meta")) + +# Map section names to custom names +generate_news_from_changelog( + section_name_mapping = c("Added" = "Features", "Fixed" = "Bug Fixes") +) + +# Use custom ordered groups +custom_ordered_groups <- c( + "Breaking Changes", "Features", "Bug Fixes", "Documentation", "Testing" +) +generate_news_from_changelog(ordered_groups = custom_ordered_groups) + +} +} +\seealso{ +\code{\link[=use_github_action_news]{use_github_action_news()}} for implementing this into a GitHub Action +Workflow. +} diff --git a/man/use_github_action_news.Rd b/man/use_github_action_news.Rd new file mode 100644 index 0000000..d24f92e --- /dev/null +++ b/man/use_github_action_news.Rd @@ -0,0 +1,38 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/pkg_news.R +\name{use_github_action_news} +\alias{use_github_action_news} +\title{Generate GitHub Action Workflow for NEWS.md Generation} +\usage{ +use_github_action_news( + file_name = "news.yml", + news_md_path = "NEWS.md", + changelog_path = "CHANGELOG.md", + overwrite = TRUE, + verbose = TRUE +) +} +\arguments{ +\item{file_name}{Name of the output workflow file (default: \code{news.yml}).} + +\item{changelog_path}{Path to the \code{CHANGELOG.md} file (default: \code{CHANGELOG.md}).} + +\item{overwrite}{Logical indicating whether to overwrite the existing workflow file (default: \code{TRUE}).} + +\item{verbose}{Logical indicating whether to display messages (default: \code{TRUE}).} + +\item{config_path}{Path to the \code{cliff.toml} configuration file (default: \code{.github/cliff.toml}).} +} +\value{ +Invisibly returns \code{NULL}. +} +\description{ +This function generates a GitHub Action workflow YAML file that automates +the generation of \code{NEWS.md} from \code{CHANGELOG.md} whenever changes are pushed +to the repository. +} +\examples{ +if (interactive()) { + generate_github_action_workflow() +} +}