Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@jeroen
jeroen committed May 27, 2019
1 parent ded3cd7 commit 03f767f
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 160 deletions.
85 changes: 15 additions & 70 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,93 +19,38 @@ knitr::opts_chunk$set(
[![Build Status](https://travis-ci.org/ropensci/rotemplate.svg?branch=master)](https://travis-ci.org/ropensci/rotemplate)
<!-- badges: end -->

rotemplate provides a custom pkgdown template for rOpenSci packages. Please don’t use it for your own package if it's not an rOpenSci package (i.e. only use it for packages listed on https://ropensci.org/packages/).
rotemplate provides a custom pkgdown template for rOpenSci packages. We use this to render sites at `https://docs.ropensci.org`. Please don’t use it for your own package if it's not an rOpenSci package (i.e. only use it for packages listed on https://ropensci.org/packages/).

Inspired by [tidytemplate](https://github.com/tidyverse/tidytemplate/) and [lockedatapkg](https://github.com/lockedatapublished/lockedatapkg).

## How to use `rotemplate`

### If your website has no `pkgdown` website yet

Run the code below to create a `pkgdown` config file that already uses the `rotemplate` package.
Documentation rOpenSci packages will automatically be generated from your master branch and published to https://docs.ropensci.org. You don't have to do anything to make this work. If you want to test your site locally use this:

```r
# remotes::install_github("ropenscilabs/rodev")
rodev::use_ro_pkgdown()
```

And to ensure your website will be automatically deployed from Travis, which we recommend,

```r
usethis::use_pkgdown_travis()
```

Note that the setup that'll be recommended by running the function above consists in updating the website on a gh-pages branch with every push, which
might bloat your git history. If you want to avoid that, have a look at

* the [setup in `magick` repo](https://github.com/ropensci/magick/blob/e8895c35df8a985212cc5b094a2aaad7389d029d/.travis.yml#L14): the website is only built when there's a GitHub release, which uses the following code in its `.travis.yml` file.

```yaml
deploy:
provider: script
script: Rscript -e 'pkgdown::deploy_site_github()'
skip_cleanup: true
on:
tags: true
template <- list(package = "rotemplate")
pkgdown::build_site(devel = FALSE, override = list(template = template))
```

* The [Travis-free, Makefile-based setup in `cyphr` repo](https://github.com/ropensci/cyphr). The gh-pages branch is created anew each time the website is updated. The website is built locally.
Everything else can be configured as usual via the `_pkgdown.yml` file as described in the pkgdown documentation.

### In all cases
If your website is not deploying or you run into another problem, please open an issue in the [ropensci/docs](https://github.com/ropensci/docs) repository.

#### Tweak `_pkgdown.yml` config
## Example sites

In your `_pkgdown.yml` config file make sure to add the following lines
* [`cyphr`](https://docs.ropensci.org/cyphr/)

```yaml
template:
package: rotemplate
```
* [`drake`](https://docs.ropensci.org/drake/)

#### Tweak the `.travis.yml` config
* [`riem`](https://docs.ropensci.org/riem/)

To `.travis.yml` add a command installing the package template, i.e. something like
* [`ropenaq`](https://docs.ropensci.org/ropenaq/)

```yaml
before_cache:
Rscript -e 'remotes::install_cran("pkgdown");remotes::install_github("ropensci/rotemplate").'
```
* [`rotl`](https://docs.ropensci.org/rotl/)

Locally, if you want to build and preview the website, you'll need to ensure that `rotemplate` is installed, and then build your website:

```r
remotes::install_github("ropensci/rotemplate")
pkgdown::build_site()
```
* [`stplanr`](https://docs.ropensci.org/stplanr/)

#### Make sure the website has a favicon

If your package has no logo of its own, use the rOpenSci hex by running the code below, that will create a pkgdown/ folder with favicon files.

```r
# remotes::install_github("ropenscilabs/rodev")
rodev::use_ro_favicon()
```

If your package has a logo, run `usethis::use_logo()` with the path to it, and then `pkgdown::build_favicon()`.

## Examples "in the wild"

* [`cyphr`](https://ropensci.github.io/cyphr/)

* [`drake`](https://ropensci.github.io/drake/)

* [`riem`](https://ropensci.github.io/riem/)

* [`ropenaq`](https://ropensci.github.io/ropenaq/)

* [`rotl`](https://ropensci.github.io/rotl/)
* [`visdat`](http://visdat.njtierney.com/)

* [`stplanr`](https://ropensci.github.io/stplanr/)
* [`magick`](https://docs.ropensci.org/magick/)

* [`visdat`](http://visdat.njtierney.com/)
114 changes: 24 additions & 90 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,113 +12,47 @@ public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostat
Status](https://travis-ci.org/ropensci/rotemplate.svg?branch=master)](https://travis-ci.org/ropensci/rotemplate)
<!-- badges: end -->

rotemplate provides a custom pkgdown template for rOpenSci packages.
Please don’t use it for your own package if it’s not an rOpenSci package
(i.e. only use it for packages listed on
<https://ropensci.org/packages/>).
rotemplate provides a custom pkgdown template for rOpenSci packages. We
use this to render sites at `https://docs.ropensci.org`. Please don’t
use it for your own package if it’s not an rOpenSci package (i.e. only
use it for packages listed on <https://ropensci.org/packages/>).

Inspired by [tidytemplate](https://github.com/tidyverse/tidytemplate/)
and [lockedatapkg](https://github.com/lockedatapublished/lockedatapkg).

## How to use `rotemplate`

### If your website has no `pkgdown` website yet

Run the code below to create a `pkgdown` config file that already uses
the `rotemplate` package.

``` r
# remotes::install_github("ropenscilabs/rodev")
rodev::use_ro_pkgdown()
```

And to ensure your website will be automatically deployed from Travis,
which we recommend,

``` r
usethis::use_pkgdown_travis()
```

Note that the setup that’ll be recommended by running the function above
consists in updating the website on a gh-pages branch with every push,
which might bloat your git history. If you want to avoid that, have a
look at

- the [setup in `magick`
repo](https://github.com/ropensci/magick/blob/e8895c35df8a985212cc5b094a2aaad7389d029d/.travis.yml#L14):
the website is only built when there’s a GitHub release, which uses
the following code in its `.travis.yml` file.

<!-- end list -->

``` yaml
deploy:
provider: script
script: Rscript -e 'pkgdown::deploy_site_github()'
skip_cleanup: true
on:
tags: true
```
- The [Travis-free, Makefile-based setup in `cyphr`
repo](https://github.com/ropensci/cyphr). The gh-pages branch is
created anew each time the website is updated. The website is built
locally.

### In all cases

#### Tweak `_pkgdown.yml` config

In your `_pkgdown.yml` config file make sure to add the following lines

``` yaml
template:
package: rotemplate
```

#### Tweak the `.travis.yml` config

To `.travis.yml` add a command installing the package template,
i.e. something like

``` yaml
before_cache:
Rscript -e 'remotes::install_cran("pkgdown");remotes::install_github("ropensci/rotemplate").'
```

Locally, if you want to build and preview the website, you’ll need to
ensure that `rotemplate` is installed, and then build your website:
Documentation rOpenSci packages will automatically be generated from
your master branch and published to <https://docs.ropensci.org>. You
don’t have to do anything to make this work. If you want to test your
site locally use this:

``` r
remotes::install_github("ropensci/rotemplate")
pkgdown::build_site()
template <- list(package = "rotemplate")
pkgdown::build_site(devel = FALSE, override = list(template = template))
```

#### Make sure the website has a favicon

If your package has no logo of its own, use the rOpenSci hex by running
the code below, that will create a pkgdown/ folder with favicon files.

``` r
# remotes::install_github("ropenscilabs/rodev")
rodev::use_ro_favicon()
```
Everything else can be configured as usual via the `_pkgdown.yml` file
as described in the pkgdown documentation.

If your package has a logo, run `usethis::use_logo()` with the path to
it, and then `pkgdown::build_favicon()`.
If your website is not deploying or you run into another problem, please
open an issue in the [ropensci/docs](https://github.com/ropensci/docs)
repository.

## Examples “in the wild”
## Example sites

- [`cyphr`](https://ropensci.github.io/cyphr/)
- [`cyphr`](https://docs.ropensci.org/cyphr/)

- [`drake`](https://ropensci.github.io/drake/)
- [`drake`](https://docs.ropensci.org/drake/)

- [`riem`](https://ropensci.github.io/riem/)
- [`riem`](https://docs.ropensci.org/riem/)

- [`ropenaq`](https://ropensci.github.io/ropenaq/)
- [`ropenaq`](https://docs.ropensci.org/ropenaq/)

- [`rotl`](https://ropensci.github.io/rotl/)
- [`rotl`](https://docs.ropensci.org/rotl/)

- [`stplanr`](https://ropensci.github.io/stplanr/)
- [`stplanr`](https://docs.ropensci.org/stplanr/)

- [`visdat`](http://visdat.njtierney.com/)

- [`magick`](https://docs.ropensci.org/magick/)

0 comments on commit 03f767f

Please sign in to comment.