README.Rmd

---
output: 
  github_document:
    html_preview: false
---

```{r setup, include=FALSE, message=FALSE, warning=TRUE}
knitr::opts_chunk$set(message = FALSE, warning = FALSE, fig.align = 'center', fig.path = "man/figures/")
```

```{r render_md_output, include=FALSE}
markdown_output <- function(x, ...) {
  res <- paste(">", strsplit(x, "\n")[[1L]], collapse = "\n")
  knitr::asis_output(res)
}
```

# rd2markdown

[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/rd2markdown)](https://cran.r-project.org/package=rd2markdown)
[![R build status](https://github.com/Genentech/rd2markdown/workflows/R-CMD-check/badge.svg)](https://github.com/Genentech/rd2markdown/actions?query=workflow%3AR-CMD-check)
[![Codecov test coverage](https://codecov.io/gh/Genentech/rd2markdown/branch/main/graph/badge.svg)](https://app.codecov.io/gh/Genentech/rd2markdown?branch=main)
[![Total Downloads](http://cranlogs.r-pkg.org/badges/grand-total/rd2markdown?color=orange)](http://cranlogs.r-pkg.org/badges/grand-total/rd2markdown)

# Overview

The `rd2markdown` package provides a way to conveniently convert .Rd package
documentation files into markdown files. Documentation can be acquired in
various ways, for instance using the documentation page of an already installed
package, or by fetching it directly from the source file. The package aims to
help other developers in presenting their work, by converting documentation of
their packages to markdown files that later can be funneled into a report,
README, and any others. Therefore there are countless different scenarios where
this tool might be useful. We plan to drive the development of `rd2markdown` in
a way it will address the needs of the R community.

The core logic behind the whole conversion is treating each rd tag as a separate
class. We take the documentation object and parse it layer by layer like an
onion. Thanks to that, each tag receives a dedicated treatment so it can be
presented basically according to the demand. On top of that, it makes the
package way more extensible, as adding the support of a new tag is essentially
just implementing another method. 

# Installation

Install the development version from GitHub:

```{r eval=FALSE}
remotes::install_github("Genentech/rd2markdown")
```

or latest CRAN version

```{r eval=FALSE}
install.packages("rd2markdown")
```

# Examples

Below are some basic examples that show the core functionalities of the
`rd2markdown`, its strong sides and possibilities it provides for the R
community.

## Rendering from file path

```{r, render=markdown_output, results='asis'}
rd_example <- system.file("examples", "rd_file_sample.Rd", package = "rd2markdown")
rd <- rd2markdown::get_rd(file = rd_example)
rd2markdown::rd2markdown(rd, fragments = c("title", "description", "details"))
```

## Rendering from help alias

```{r, render=markdown_output, results='asis'}
rd2markdown::rd2markdown(
  topic = "rnorm",
  package = "stats",
  fragments = c("title", "description", "usage")
)
```

To see the examples showing the complexity of the package, please take a look at
the vignette attached in this package `The rd2markdown package intro`. You will
find there not only examples for all exported functions with various
combinations of parameters, but also the rationale for this package, why it was
created, and what logic it follows.

# Plans for the future development

Below is the list of our plans for the nearest future`;

1. Publish to CRAN
2. Bug fixes