https://github.com/ThinkR-open/papillon
Build And Highlight Package Documentation With Customized Templates
https://github.com/ThinkR-open/papillon
Last synced: 4 months ago
JSON representation
Build And Highlight Package Documentation With Customized Templates
- Host: GitHub
- URL: https://github.com/ThinkR-open/papillon
- Owner: ThinkR-open
- License: gpl-3.0
- Created: 2019-07-04T12:42:41.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2023-01-28T15:09:21.000Z (about 2 years ago)
- Last Synced: 2024-11-28T21:53:03.870Z (5 months ago)
- Language: R
- Homepage: https://thinkr-open.github.io/papillon/
- Size: 343 KB
- Stars: 11
- Watchers: 2
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- jimsghstars - ThinkR-open/papillon - Build And Highlight Package Documentation With Customized Templates (R)
README
---
output: github_document
---
[](https://www.tidyverse.org/lifecycle/#experimental)
[](https://github.com/ThinkR-open/papillon/actions)
[](https://app.codecov.io/gh/ThinkR-open/papillon?branch=main)
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# papillon
This is package {papillon}: Build And Highlight Package Documentation With Customized
Templates.
You are using version 0.0.1.9000.
*Complete documentation in the {pkgdown} site: https://thinkr-open.github.io/papillon/*
## Installation
The list of dependencies required to install this package is: attachment, bookdown, cli, crayon, desc, devtools, knitr, magrittr, pkgdown, readr, remotes, rmarkdown, shiny, usethis, utils.
To install the package, you can run the following script
```{r, echo=TRUE, eval=FALSE}
# install.packages("remotes")
remotes::install_github(repo = "Thinkr-open/papillon")
```
## Examples
### Build a book from vignettes inside a package
You can use `create_book()` using your own template basis. By default, it uses {bookdown} site template. You can use it to build your own.
```{r, eval=FALSE}
template <- system.file("rstudio/templates/project/resources", package = "bookdown")
create_book(path = "inst/report", clean = TRUE,
template = template)
```
Help users find your book with function `open_guide_function()`. This adds function `open_guide()` inside your package that will open the userguide (in HTML or PDF) on demand.
```{r, eval=FALSE}
open_guide_function(path = "inst/report")
```
### Build a pkgdown site inside a package
You can use `build_pkgdown()` using your own template basis. By default, it uses the {pkgdown} original template.
To use your own template, it is better to create a R package with all necessary files (See as an example).
*You can then define your own `_pkgdown.yml` file that will call your template when building the site:*
```yaml
template:
package: mypackagetemplate
```
```{r, eval=FALSE}
papillon::build_pkgdown(
lazy = TRUE,
yml = "/pah/to/your/yaml/_pkgdown.yml",
favicon = "/path/to/your/favicon.ico",
move = TRUE
)
```
Help users find your pkgdown website with function `open_pkgdown_function()`. This adds function `open_pkgdown()` inside your package that will open the site on demand. _This may make your package not pass warnings in checks, but remember this is for internal or private use. For public use, you can publish your pkgdown site directly online._
```{r, eval=FALSE}
papillon::open_pkgdown_function()
```
### Build a reference page
To award people hard working for open-source, it is always good to cite their work. In order to add an informative page in your Shiny applications for instance, you can create a html or markdown page listing all package dependencies used.
```{r, eval=FALSE}
papillon::create_pkg_biblio_file(to = "html", out.dir = "inst")
# Can be included in a shiny app using
shiny::includeHTML("bibliography.html")
# OR
papillon::create_pkg_biblio_file(to = "markdown")
# Can be included in a shiny app using
shiny::includeMarkdown("bibliography.md")
```
## To describe your package and how to install it
This can be useful to create your Readme for instance or to send the instructions file for your clients to install your package.
```{r, eval=FALSE}
path <- system.file("DESCRIPTION", package = "papillon")
out.dir <- tempdir()
create_pkg_desc_file(path, source = c("archive"), to = "html")
```
```{r, eval=FALSE}
# Use with results="asis" in a Rmd
shiny::includeHTML(file.path(out.dir, "pkg_description.html"))
```
## Create and update a custom README with installation instructions
- `generate_readme()` uses {usethis} Readme template for packages and fill the installation instructions.
- This function can be run anytime during project development as it will only update the description and installation parts
```{r, eval=FALSE}
#usethis::use_readme_rmd
papillon::generate_readme_rmd()
papillon::generate_readme_rmd(parts = "description")
```
## Code of Conduct
Please note that the papillon project is released with a [Contributor Code of Conduct](https://thinkr-open.github.io/papillon/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.