Prepare for release:

• git pull
• Check current CRAN check results
• usethis::use_news_md()
• Polish NEWS
• usethis::use_github_links()
• urlchecker::url_check()
• devtools::check(remote = TRUE, manual = TRUE)
• devtools::check_win_devel()
• revdepcheck::revdep_check(num_workers = 4)
• Update cran-comments.md
• git push

Submit to CRAN:

• devtools::submit_cran()
• Approve email

Here's an example of a .Rd file, called test_rd.Rd:

\name{foo}
\title{Some title}
\details{
    Some basic text.
    \subsection{First subsection}{
        This is some text in a subsection.
    }
    \subsection{Second subsection}{
        Here's a second subsection.
    }
}

When I render it with Rd2md::Rd2markdown("test_rd.Rd", outfile = "foo.md"), it gives:

# `foo`

Some title


## Details

Some basic text.
  list(list("First subsection"), list("\n", "        This is some text in a subsection.\n", "    ")) 
  list(list("Second subsection"), list("\n", "        Here's a second subsection.\n", "    "))

Clearly, the subsections in Details are not formatted properly. Could you consider reformatting them with ### for instance?

Briefly mentioned in #20, when parsing single files (and hence not providing pkg_path in parse_rd_file), there is an error due to the NULL default value.

This is due to a change in tools::loadPkgRdMacros in 4.3.0.

Requires further investigation, a short reprex and review of #19.

Paragraphs are not handled as they should:

test_that("Paragraphs are handled correctly", {
  expect_equal(rd_str_to_md("line-one\nline-two"), "line-one\nline-two\n")

  # TODO: these tests fail, fix behaviour:
  expect_equal(
    rd_str_to_md("paragraph-one\n\nparagraph-two"),
    "paragraph-one\n\nparagraph-two\n"
  )
  expect_equal(
    rd_str_to_md("paragraph-one\n\n\nparagraph-two"),
    "paragraph-one\n\nparagraph-two\n"
  )
})

Hi @quantsch 👋

I'm reaching out on behalf of Genentech/rd2markdown, developed primarily by myself and @maksymiuks.

We started development on rd2markdown a couple years back. Rd2md existed that time, but development looked like it was a bit sporadic and was lacking a few key features that we needed urgently so we whipped up something that suited our needs at the time. At that time, Rd2md used a collection of if-else blocks to handle Rd tags and that structure didn't quite live up to the level of extensibility that we needed.

Fast forward to today, and we're preparing to present on rd2markdown at the upcoming UseR! We wanted to check in with this project before sharing our progress. When checking in on the status, we were very happy to see that development seems to be more constant and that you have undertaken quite an impressive refactor exercise that really starts to make the packages look very similar architecturally to ours!

Seeing that both packages have similar goals, and more recently even have similar design, we wanted to reach out to float the idea of merging efforts.

Hello, very nice package that you have here!

I am considering using it in one of my packages, but at the same time I'd like to reduce non-essential dependencies. One of my concerns is that it might break in the future, so I'm wondering: do you plan on adding some tests?

I'm currently documenting some s4 classes, where you describe the slots with @slot. But these describtions aren't included in the final md file when I use rd2Rmarkdown. I'd like them to appear like the Argument section. Is there a reason why they aren't printed to the .md output?

Reffering to your code it should be in results$section.

@quantsch Thanks so much for this package! I use it in my own r2readthedocs package, and we @ropensci also use it in our own meta-documentation suite.

Through that usage, I had seen your deprecation warnings, and got around to updating things today. Nice work on the great improvements to the package, which definitely make it more robust and flexible. Thanks for that!

That said, the error encountered in #19 meant that I had to figure out what was going wrong, which required me to try to understand the new as_markdown() function. I could find nothing in the documentation to help that function make sense, and the sole recommendation that people read the vignette is useful, but my usages are almost entirely based on file rather than package translations, so that didn't help either. The README jumps straight through to "Extension" before describing how to actually use the main functionality. That left me at a complete loss, and I had to clone the repo and read through the actual code to understand how to use it.

Please consider this issue either as a motivation yourself to improve the documentation both of the main package entry points of README and in https://github.com/quantsch/Rd2md/blob/main/R/Rd2md-package.R, as well as documentation of the main functions. Or, if you're willing, I'd be happy to do you the hopefully helpful favour of casting a pair of external eyes over those bits and drafting an initial PR for you?

Thanks again for the great work in further developing this really useful package!

Is there any support planned or already in place for R6 classes documentation? Currently it seems to omit documentation for all methods. Is this linked with #6 ?

If the codes in Examples section are wrapped with \dontrun{}, generated text is unexpectedly wrapped with list(...).

tmp_rd <- tempfile(fileext = ".Rd")
download.file("https://raw.githubusercontent.com/mlflow/mlflow/c3609a77e9705172845c652580b606b63a696d13/mlflow/R/mlflow/man/mlflow_cli.Rd",
              destfile = tmp_rd)

rd <- tools::parse_Rd(tmp_rd)
Rd2md::parseRd(rd)$examples
#> [1] "\n list(\"\\n\", \"library(mlflow)\\n\", \"mlflow_install()\\n\", \"\\n\", \"mlflow_cli(\\\"server\\\", \\\"--help\\\")\\n\") \n \n"

The reason is that \dontrun{} section is a nested list, which means it should be flattened by unlist() or something before paste()ing into one text.

tags <- purrr::map_chr(rd, attr, "Rd_tag")

rd[[which(tags == "\\examples")]]
#> [[1]]
#> [1] "\n"
#> attr(,"Rd_tag")
#> [1] "RCODE"
#> 
#> [[2]]
#> [[2]][[1]]
#> [1] "\n"
#> attr(,"Rd_tag")
#> [1] "VERB"
#> 
#> [[2]][[2]]
#> [1] "library(mlflow)\n"
#> attr(,"Rd_tag")
#> [1] "VERB"
#> 
#> [[2]][[3]]
#> [1] "mlflow_install()\n"
#> attr(,"Rd_tag")
#> [1] "VERB"
#> 
#> [[2]][[4]]
#> [1] "\n"
#> attr(,"Rd_tag")
#> [1] "VERB"
#> 
#> [[2]][[5]]
#> [1] "mlflow_cli(\"server\", \"--help\")\n"
#> attr(,"Rd_tag")
#> [1] "VERB"
#> 
#> attr(,"Rd_tag")
#> [1] "\\dontrun"
#> 
#> [[3]]
#> [1] "\n"
#> attr(,"Rd_tag")
#> [1] "RCODE"
#> 
#> [[4]]
#> [1] "\n"
#> attr(,"Rd_tag")
#> [1] "RCODE"
#> 
#> attr(,"Rd_tag")
#> [1] "\\examples"

paste(
  Rd2md:::parseTag(rd[[which(tags == "\\examples")]], stripNewline = FALSE)
)
#> [1] "\n"                                                                                                                        
#> [2] "list(\"\\n\", \"library(mlflow)\\n\", \"mlflow_install()\\n\", \"\\n\", \"mlflow_cli(\\\"server\\\", \\\"--help\\\")\\n\")"
#> [3] "\n"                                                                                                                        
#> [4] "\n"

paste(
  unlist(
    Rd2md:::parseTag(rd[[which(tags == "\\examples")]], stripNewline = FALSE),
    recursive = FALSE
  )
)
#> [1] "\n"                                  
#> [2] "\n"                                  
#> [3] "library(mlflow)\n"                   
#> [4] "mlflow_install()\n"                  
#> [5] "\n"                                  
#> [6] "mlflow_cli(\"server\", \"--help\")\n"
#> [7] "\n"                                  
#> [8] "\n"

^{Created on 2018-10-04 by the reprex package (v0.2.1)}

Hey,
I want to utilize your Rd2markdown function for exporting package documentation into a Quarto project. Therefore, I need the headers to have a specific level (in my case, 3 and 4). In your implementation, the header size is fixed. I would propose an additional parameter that let the user pass a header size to the function. The section and subsection header will then be generated dynamic. If you would like to have this feature, I can open a PR with an implementation.

Please let me know if you have any suggestions.

Jakob