Support level 1 headings in markdown

NAMESPACE

@@ -103,6 +103,7 @@ export(tag_code)
 export(tag_examples)
 export(tag_inherit)
 export(tag_markdown)
+export(tag_markdown_with_sections)
 export(tag_name)
 export(tag_name_description)
 export(tag_toggle)

R/markdown.R

@@ -1,21 +1,22 @@
-markdown_if_active <- function(text, tag) {
+markdown_if_active <- function(text, tag, sections = FALSE) {
   if (markdown_on()) {
-    markdown(text, tag)
+    markdown(text, tag, sections)
   } else {
     text
   }
 }
 
-markdown <- function(text, tag = NULL) {
+markdown <- function(text, tag = NULL, sections = FALSE) {
   esc_text <- escape_rd_for_md(text)
   esc_text_linkrefs <- add_linkrefs_to_md(esc_text)
 
   mdxml <- md_to_mdxml(esc_text_linkrefs)
   state <- new.env(parent = emptyenv())
   state$tag <- tag
+  state$has_sections <- sections
   rd <- mdxml_children_to_rd_top(mdxml, state)
 
-  unescape_rd_for_md(str_trim(rd$main), esc_text)
+  map_chr(rd, unescape_rd_for_md, esc_text)
 }
 
 md_to_mdxml <- function(x) {
@@ -29,7 +30,7 @@ mdxml_children_to_rd_top <- function(xml, state) {
   out <- c(out, mdxml_close_sections(state))
   rd <- paste0(out, collapse = "")
   secs <- strsplit(rd, state$section_tag, fixed = TRUE)[[1]]
-  list(main = secs[[1]], sections = secs[-1])
+  str_trim(secs)
 }
 
 mdxml_children_to_rd <- function(xml, state) {
@@ -175,7 +176,7 @@ escape_comment <- function(x) {
 
 mdxml_heading <- function(xml, state) {
   level <- xml_attr(xml, "level")
-  if (state$tag$tag != "@includeRmd" && level == 1) {
+  if (! state$has_sections && level == 1) {
     return(mdxml_unsupported(xml, state$tag, "level 1 markdown headings"))
   }
   head <- paste0(

R/rd-include-rmd.R

@@ -54,6 +54,7 @@ rmd_eval_rd <- function(path, tag) {
   mdxml <- xml2::read_xml(mdx)
   state <- new.env(parent = emptyenv())
   state$tag <- tag
+  state$has_sections <- TRUE
   rd <- mdxml_children_to_rd_top(mdxml, state = state)
   rd
 }

R/rd.R

@@ -41,8 +41,8 @@ roclet_tags.roclet_rd <- function(x) {
     backref = tag_value,
     concept = tag_markdown,
     describeIn = tag_name_description,
-    description = tag_markdown,
-    details = tag_markdown,
+    description = tag_markdown_with_sections,
+    details = tag_markdown_with_sections,
     docType = tag_name,
     encoding = tag_value,
     evalRd = tag_code,
@@ -243,7 +243,12 @@ topic_add_simple_tags <- function(topic, block) {
   tag_names <- names(block)[is_simple]
 
   for (i in seq_along(tag_values)) {
-    topic$add_simple_field(tag_names[[i]], tag_values[[i]])
+    if (length(tag_values[[i]]) && nchar(tag_values[[i]][[1]])) {
+      topic$add_simple_field(tag_names[[i]], tag_values[[i]][[1]])
+    }
+    for (sec in tag_values[[i]][-1]) {
+      topic$add_simple_field("rawRd", sec)
+    }
   }
 }
 
@@ -411,7 +416,7 @@ topic_add_include_rmd <- function(topic, block, base_path) {
 
   for (rmd in rmds) {
     tag <- roxy_tag(
-      "@includeRmd",
+      "includeRmd",
       rmd,
       attr(block, "filename"),
       attr(block, "location")[[1]]
@@ -420,10 +425,10 @@ topic_add_include_rmd <- function(topic, block, base_path) {
       roxy_tag_warning(tag, "Needs the rmarkdown package")
     }
     out <- block_include_rmd(tag, block, base_path)
-    if (!is.null(out$main)) {
-      topic$add_simple_field("details", out$main)
+    if (!is.null(out[[1]])) {
+      topic$add_simple_field("details", out[[1]])
     }
-    lapply(out$sections, function(s) {
+    lapply(out[-1], function(s) {
       topic$add_simple_field("rawRd", s)
     })
   }

R/tag.R

@@ -241,3 +241,23 @@ tag_markdown <- function(x) {
   x$val <- markdown_if_active(x$val, x)
   tag_value(x)
 }
+
+#' @export
+#' @rdname roxy_tag
+tag_markdown_with_sections <- function(x) {
+  if (x$val == "") {
+    return(roxy_tag_warning(x, "requires a value"))
+  }
+
+  x$val <- markdown_if_active(x$val, x, sections = TRUE)
+  for (i in seq_along(x$val)) {
+    if (!rdComplete(x$val[i])) {
+      roxy_tag_warning(x, "mismatched braces or quotes")
+      x$val[i] <- ""
+    } else {
+      x$val[i] <- str_trim(x$val[i])
+    }
+  }
+
+  x
+}

tests/testthat/test-markdown.R

@@ -404,10 +404,11 @@ test_that("unhandled markdown generates warning", {
   expect_warning(roc_proc_text(rd_roclet(), text), "block quotes")
 })
 
-test_that("level 1 heading in markdown generates warning", {
+test_that("level 1 heading in markdown generates warning in some tags", {
   text <- "
     #' Title
     #'
+    #' @seealso this and that
     #' # This is not good
     #'
     #' Blabla
@@ -482,3 +483,69 @@ test_that("level >2 markdown headings work in @return", {
     "Even this\n\\subsection{Can have a subsection.}{\n\nYes.\n}"
   )
 })
+
+test_that("level 1 heading in @details", {
+  text1 <- "
+    #' Title
+    #'
+    #' Description.
+    #'
+    #' @details
+    #' Leading text goes into details.
+    #' # This is its own section
+    #' ## Can have a subsection
+    #' Yes.
+    #' # Another section
+    #' With text.
+    #' @md
+    #' @name x
+    NULL
+  "
+  out1 <- roc_proc_text(rd_roclet(), text1)[[1]]
+  text2 <- "
+    #' Title
+    #'
+    #' Description.
+    #' @details
+    #' Leading text goes into details.
+    #' @rawRd
+    #' \\section{This is its own section}{
+    #' \\subsection{Can have a subsection}{
+    #'
+    #' Yes.
+    #' }
+    #'
+    #' }
+    #' @rawRd
+    #' \\section{Another section}{
+    #'
+    #' With text.
+    #' }
+    #' @name x
+    NULL
+  "
+  out2 <- roc_proc_text(rd_roclet(), text2)[[1]]
+
+  # make sure fields are in the same order
+  expect_equal(sort(names(out1$fields)), sort(names(out2$fields)))
+  out2$fields <- out2$fields[names(out1$fields)]
+
+  expect_equivalent_rd(out1, out2)
+})
+
+test_that("headings and empty sections", {
+  text1 <- "
+    #' Title
+    #'
+    #' Description.
+    #'
+    #' @details
+    #' # This is its own section
+    #' With text.
+    #' @md
+    #' @name x
+    NULL
+  "
+  out1 <- roc_proc_text(rd_roclet(), text1)[[1]]
+  expect_false("details" %in% names(out1$fields))
+})

tests/testthat/test-rd-includermd.R

@@ -11,21 +11,20 @@ test_that("markdown file can be included", {
     #' @name foobar
     NULL", tmp)
   out1 <- roc_proc_text(rd_roclet(), rox)[[1]]
-  out1$fields$details$values <- str_trim(out1$fields$details$values)
   out2 <- roc_proc_text(rd_roclet(), "
-    #' @details
-    #'
-    #'
-    #' List:
+    #' @title Title
+    #' @details List:
     #' \\itemize{
     #' \\item item1
     #' \\item item2
     #' }
     #'
     #' Inline \\code{code} and \\emph{emphasis}.
-    #' @title Title
     #' @name foobar
     NULL")[[1]]
+  # make sure fields are in the same order
+  expect_equal(sort(names(out1$fields)), sort(names(out2$fields)))
+  out2$fields <- out2$fields[names(out1$fields)]
   expect_equivalent_rd(out1, out2)
 })
 

vignettes/rd-formatting.Rmd

@@ -49,6 +49,34 @@ Here is an example roxygen chunk that uses markdown.
 
 # Syntax
 
+## Sections
+
+The usual markdown heading markup creates sections and subsections. Top level headings, i.e. '`#`' create sections, via the `\section{}` Rd tag. '`#`' may only appear after the `@description` and `@details` tags. Since `@details` can appear multiple times in a block, you can always precede a '`#`' section with `@details`, if you prefer to place it towards the end of the block, after `@return` for example:
+
+```r
+#' @details
+#' Trim the leading and trailing whitespace from a character vector.
+#'
+#' @param x Character vector.
+#' @return Character vector, with the whitespace trimmed.
+#'
+#' @details # This will be a new section
+#' ...
+```
+
+Top level sections are always placed at a fixed position in the manual page, after the parameters and the details, but before `\note{}`, `\seealso{}` and the `\examples{}`. Their order will be the same as in the roxygen block.
+
+## Subsections
+
+Headings at level two and above may appear inside any roxygen tag that formats lines of text. E.g. `@description`, `@details`, `@return`, etc. They create subsections, via the `\subsection{}` Rd tag. They are allowed within top level sections as well, i.e. after '`#`'. Subsections can be nested. Example:
+
+```r
+#' @details
+#' ## Subsection within details
+#' ### Sub-subsection
+#' ... text ...
+```
+
 ## Emphasis
 
 *Emphasis* and **strong** (bold) text are supported. For emphasis, put the text between asterisks or underline characters. For strong text, use two asterisks at both sides.