Authors flexibility and home/authors docs

NEWS.md

@@ -1,5 +1,14 @@
 # pkgdown (development version)
 
+* Make authors configuration more flexible: users can now
+  * Choose the roles used for filtering authors for the sidebar and footer.
+  * Choose the text before authors in the footer.
+  * Add text before and after the authors list of the authors page.
+
+* Make authors' non-ORCID comments from DESCRIPTION more usable as bio/description of 
+  contributions: add a link to the authors page from the sidebar if any author
+  has a non-ORCID comment, and only render non-ORCID comments on the authors page.
+
 * Make footer specification more flexible: users can now
     * change the placement of elements on the left and right
     * add text to the left and right (or even remove/replace default text)

R/build-home-authors.R

@@ -1,4 +1,4 @@
-data_authors <- function(pkg = ".") {
+data_authors <- function(pkg = ".", roles = default_roles()) {
   pkg <- as_pkgdown(pkg)
   author_info <- data_author_info(pkg)
 
@@ -7,18 +7,30 @@ data_authors <- function(pkg = ".") {
     purrr::map(author_list, author_info)
 
   main <- pkg %>%
-    pkg_authors(c("aut", "cre", "fnd")) %>%
+    pkg_authors(roles) %>%
     purrr::map(author_list, author_info)
 
-  needs_page <- length(main) != length(all)
+  more_authors <- length(main) != length(all)
+
+  comments <- pkg %>%
+    pkg_authors() %>%
+    purrr::map(author_list, author_info) %>%
+    purrr::map("comment") %>%
+    purrr::compact() %>%
+    length() > 0
 
   print_yaml(list(
     all = all,
     main = main,
-    needs_page = needs_page
+    more_authors = more_authors,
+    comments = comments
   ))
 }
 
+default_roles <- function() {
+  c("aut", "cre", "fnd")
+}
+
 pkg_authors <- function(pkg, role = NULL) {
   if (pkg$desc$has_fields("Authors@R")) {
     authors <- unclass(pkg$desc$get_authors())
@@ -59,11 +71,18 @@ data_author_info <- function(pkg = ".") {
 
 data_home_sidebar_authors <- function(pkg = ".") {
   pkg <- as_pkgdown(pkg)
-  data <- data_authors(pkg)
+  data <- data_authors(
+    pkg,
+    roles = pkg$meta$authors$sidebar$roles %||% default_roles()
+  )
 
-  authors <- data$main %>% purrr::map_chr(author_desc)
-  if (data$needs_page) {
+  authors <- data$main %>% purrr::map_chr(author_desc, comment = FALSE)
+  if (data$more_authors) {
     authors <- c(authors, "<a href='authors.html'>All authors...</li>")
+  } else {
+    if (data$comments) {
+      authors <- c(authors, "<a href='authors.html'>More on authors...</li>")
+    }
   }
 
   sidebar_section("Developers", authors)
@@ -72,12 +91,28 @@ data_home_sidebar_authors <- function(pkg = ".") {
 build_authors <- function(pkg = ".") {
   pkg <- as_pkgdown(pkg)
 
-  data <- list(
+  data <- data_authors_page(pkg)
+
+  render_page(pkg, "authors", data, "authors.html")
+}
+
+data_authors_page <- function(pkg) {
+   data <- list(
     pagetitle = "Authors",
-    authors = data_authors(pkg)$all
+    authors = data_authors(pkg)$all,
+    before = "",
+    after = ""
   )
 
-  render_page(pkg, "authors", data, "authors.html")
+  if (!is.null(pkg$meta$authors$before)) {
+    data$before <- markdown_text2(pkg$meta$authors$before, pkg = pkg)
+  }
+
+    if (!is.null(pkg$meta$authors$after)) {
+    data$after <- markdown_text2(pkg$meta$authors$after, pkg = pkg)
+    }
+
+  return(data)
 }
 
 author_name <- function(x, authors) {
@@ -109,7 +144,7 @@ format_author_name <- function(given, family) {
   }
 }
 
-author_list <- function(x, authors_info, comment = FALSE) {
+author_list <- function(x, authors_info = NULL, comment = FALSE) {
   name <- author_name(x, authors_info)
 
   roles <- paste0(role_lookup[x$role], collapse = ", ")

R/build-home.R

@@ -3,185 +3,8 @@
 #' This function generates the home page, converts `.md` files found in the
 #' package root (and in `.github/`), and builds an authors page from
 #' `DESCRIPTION` and `inst/CITATION` (if present).
-#'
-#' @section Home page:
-#' The home page (`index.html`) is generated from `pkgdown/index.md`,
-#' `index.md`, or `README.md`, in that order. Most packages will use `README.md`
-#' because that's also displayed by GitHub and CRAN. Use `index.md` if you want
-#' your package website to look different to your README, and use
-#' `_pkgdown/index.md` if you don't want that file to live in your package
-#' root directory.
-#'
-#' If you use `index.Rmd` or `README.Rmd` it's your responsibility to knit
-#' the document to create the corresponding `.md`. pkgdown does not do this
-#' for you because it only touches files in the `doc/` directory.
-#'
-#' @section Sidebar:
-#' By default, the sidebar automatically populated with:
-#'
-#' *   Development status badges found in `README.md`/`index.md`. pkgdown
-#'     identifies badges in three ways:
-#'
-#'     * Any image-containing links between `<!-- badges: start -->` and
-#'       `<!-- badges: end -->`, as e.g. created by `usethis::use_readme_md()`
-#'       or `usethis::use_readme_rmd()`.
-#'
-#'     * Any image-containing links within `<div id="badges"></div>`.
-#'
-#'     * Within the first paragraph, if it only contains image-containing links.
-#'
-#' *   A link for bug reports is added if the `BugReports` field in
-#'     `DESCRIPTION` contains a link. You can use `usethis::use_github_links()`
-#'     to populate this field.
-#'
-#' *   Licensing information if `LICENSE`/`LICENCE` or `LICENSE.md`/`LICENCE.md`
-#'     files are present.
-#'
-#' *   Community information is linked in the side bar using the
-#'     `.github/CONTRIBUTING.md` and `.github/CODE_OF_CONDUCT.md` files,
-#'     if present.
-#'
-#' *   Extra markdown files in the base directory or in `.github/` are copied
-#'     to `docs/` and converted to HTML.
-#'
-#' *   Citation information from a `inst/CITATION` file is linked in the side bar
-#'     to the [authors page](https://testthat.r-lib.org/authors.html).
-#'
-#' *   Author ORCID identification numbers in the `DESCRIPTION` are linked under
-#'     "Developers" using the ORCID logo:
-#'
-#'     ```
-#'     Authors@R: c(
-#'         person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre"),
-#'           comment = c(ORCID = "0000-0003-4757-117X")
-#'         ),
-#'         person("Jay", "Hesselberth", role = "aut",
-#'           comment = c(ORCID = "0000-0002-6299-179X")
-#'         )
-#'       )
-#'     ```
-#'  You can tweak the navbar by using the YAML configuration, see the corresponding
-#'  section.
-#' @section Images and figures:
-#' If you want to include images in your `README.md`, they must be stored
-#' somewhere in the package so that they can be displayed on the CRAN website.
-#' The best place to put them is `man/figures`. If you are generating figures
-#' with R Markdown, make sure you set up `fig.path` as followed:
-#'
-#' ```
-#' knitr::opts_chunk$set(
-#'   fig.path = "man/figures/"
-#' )
-#' ```
-#'
-#' This should usually go in a block with `include = FALSE`.
-#'
-#' @section Package logo:
-#' If you have a package logo, you can include it at the top of your README in a
-#' level-one heading:
-#'
-#' ```
-#' # pkgdown <img src="man/figures/logo.png" align="right" />
-#' ```
-#'
-#' [init_site()] will also automatically create a favicon set from your package
-#' logo.
-#'
-#' @section YAML config - home:
-#' To tweak the home page, you need a section called `home`.
-#'
-#' By default, the page title and description are extracted automatically
-#' from the `Title` and `Description` fields `DESCRIPTION` (stripping
-#' single quotes off quoted words). CRAN ensures that these fields don't contain
-#' phrases like "R package" because that's obvious on CRAN. To make your
-#' package more findable with google, it's good practice to override the
-#' `title` and `description`, thinking about what people might search for:
-#'
-#' ```
-#' home:
-#'   title: An R package for pool-noodle discovery
-#'   description: >
-#'     Do you love R? Do you love pool-noodles? If so, you might enjoy
-#'     using this package to automatically discover and add pool-noodles
-#'     to your growing collection.
-#' ```
-#'
-#' (Note the use of YAML's `>`; this is a convenient way of writing paragraphs
-#' of text.)
-#'
-#' The sidebar links are automatically generated by inspecting the `URL` and
-#' `BugReports` fields of the `DESCRIPTION`. You can add additional links with a
-#' subsection called `links`, which should contain a list of `text` + `href`
-#' elements:
-#'
-#' ```
-#' home:
-#'   links:
-#'   - text: Link text
-#'     href: http://website.com
-#' ```
-#'
-#' You can change the order of sidebar components:
-#' `links`, `license` (with an "s"), `community`, `citation`,
-#' `authors`, `dev` (badges); you can add a README table of contents `toc`,
-#' you can add custom components.
-#' The example below creates a sidebar whose only components will be the
-#' authors section, a custom section, a table of contents for the README
-#' and a Dev Status section if there are badges.
-#' The `text` will be treated as Markdown.
-#'
-#' ```
-#' home:
-#'   sidebar:
-#'     structure: [authors, custom, toc, dev]
-#'     components:
-#'       custom:
-#'         title: Funding
-#'         text: We are *grateful* for funding!
-#' ```
-#'
-#' You can provide a ready-made sidebar HTML:
-#'
-#' ```
-#' home:
-#'   sidebar:
-#'     html: path-to-sidebar.html
-#' ```
-#'
-#' Finally, you can completely remove the sidebar.
-#'
-#' ```
-#' home:
-#'   sidebar: FALSE
-#' ```
-#'
-#' READMEs usually start with an `<h1>` containing the package name. If
-#' that feels duplicative with the package name in the navbar you can
-#' remove it with `strip_header: true`:
-#'
-#' ```
-#' home:
-#'   strip_header: true
-#' ```
-#'
-#' @section YAML config - authors:
-#' The "developers" list is populated by the maintainer ("cre"), authors
-#' ("aut"), and funder ("fnd") from the `DESCRIPTION`. You can modify their
-#' display on the home page by adding a subsection for `authors`. Each entry
-#' in `authors` should be named with the author's name (matching `DESCRIPTION`)
-#' and can contain `href` and/or `html` fields:
-#'
-#' * If `href` is provided, the author's name will be linked to this url.
-#' * If `html` is provided, it will be shown instead of the author's name.
-#'   This is particularly useful if you want to display the logo of a corporate
-#'   sponsor.
-#'
-#' ```
-#' authors:
-#'   firstname lastname:
-#'     href: "http://name-website.com"
-#'     html: "<img src='name-picture.png' height=24>"
-#' ```
+#' @includeRmd man/rmd-fragments/home-configuration.Rmd
+#' @includeRmd man/rmd-fragments/authors-configuration.Rmd
 #' @inheritParams build_articles
 #' @export
 build_home <- function(pkg = ".",

R/markdown.R

@@ -3,7 +3,7 @@ markdown <- function(path = NULL, ..., strip_header = FALSE, pkg) {
   on.exit(unlink(tmp), add = TRUE)
 
   if (rmarkdown::pandoc_available("2.0")) {
-    from <- "markdown+gfm_auto_identifiers-citations"
+    from <- "markdown+gfm_auto_identifiers-citations+emoji"
   } else if (rmarkdown::pandoc_available("1.12.3")) {
     from <- "markdown_github-hard_line_breaks+tex_math_dollars+tex_math_single_backslash+header_attributes"
   } else {

R/rd-html.R

@@ -100,8 +100,8 @@ as_html.tag_subsection <- function(x, ..., subsection_level = 3L) {
   h <- paste0("h", subsection_level)
 
   paste0(
-    "<", h, " class='hasAnchor' id='arguments'>",
-    "<a class='anchor' href='#arguments'></a>",
+    "<", h, " class='hasAnchor' id='", make_slug(x[[1]]),"'>",
+    "<a class='anchor' href='#", make_slug(x[[1]]), "'></a>",
     flatten_text(x[[1]], ...),
     "</", h, ">\n",
     flatten_para(x[[2]], ..., subsection_level = subsection_level + 1L)

R/render.r

@@ -72,7 +72,9 @@ render_page <- function(pkg = ".", name, data, path = "", depth = NULL, quiet =
 data_template <- function(pkg = ".", depth = 0L) {
   pkg <- as_pkgdown(pkg)
 
-  authors <- data_authors(pkg)$main %>%
+  roles <- pkg$meta$authors$footer$roles %||% default_roles()
+
+  authors <- data_authors(pkg, roles = roles)$main %>%
     purrr::map_chr("name") %>%
     paste(collapse = ", ")
 
@@ -307,7 +309,7 @@ check_made_by <- function(first) {
 pkgdown_footer <- function(data, pkg) {
 
   footer_components <- list(
-    authors = footer_authors(data),
+    authors = footer_authors(data, pkg),
     pkgdown = footer_pkgdown(data)
   )
 
@@ -354,8 +356,9 @@ pkgdown_footer <- function(data, pkg) {
   list(left = left_final_components, right = right_final_components)
 }
 
-footer_authors <- function(data) {
-  paste0("Developed by ", data$package$authors, ".")
+footer_authors <- function(data, pkg) {
+  text <- pkg$meta$authors$footer$text %||% "Developed by"
+  paste0(trimws(text), " ", data$package$authors, ".")
 }
 
 footer_pkgdown <- function(data) {

inst/templates/BS3/content-authors.html

@@ -3,7 +3,7 @@
     <div class="page-header">
       <h1>Authors</h1>
     </div>
-
+    {{{before}}}
     <ul class="list-unstyled">
       {{#authors}}
       <li>
@@ -13,6 +13,7 @@ <h1>Authors</h1>
       {{/authors}}
     </ul>
 
+    {{{after}}}
   </div>
 
 </div>

inst/templates/BS3/content-citation-authors.html

@@ -14,6 +14,7 @@ <h1>Citation</h1>
       <h1>Authors</h1>
     </div>
 
+    {{{before}}}
     <ul class="list-unstyled">
       {{#authors}}
       <li>
@@ -22,7 +23,7 @@ <h1>Authors</h1>
       </li>
       {{/authors}}
     </ul>
-
+    {{{after}}}
   </div>
 
 </div>