diff --git a/.Rbuildignore b/.Rbuildignore index f53131f0d..1f10f98b1 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -4,4 +4,10 @@ ^\.travis\.yml$ ^\.github$ ^README\.md$ +^README\.Rmd$ ^tools/ +^_pkgdown\.yml$ +^reference$ +^pkgdown$ +^vignettes$ + diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..ebcf2a918 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,126 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, +and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall +community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or +advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email +address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards +of acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies +when an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at codeofconduct@rstudio.com. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, +available at . + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +. Translations are available at . diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 000000000..20cd4cbb0 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,21 @@ +# Contributing to rticles + +We welcome contributions to the **rticles** package. + +You can contribute in many ways: + +* By opening issues to give feedback and share ideas. +* By fixing typos in documentations +* By submitting Pull Request (PR) to fix some opened issues +* By submitting Pull Request (PR) to suggest some new features. (It is considered good practice to open issues before to discuss ideas) + + +## To submit a contribution using a Pull Request: + +1. [Fork](https://github.com/rstudio/bookdown/fork) the repository and make your changes in a new branch specific to the PR. It is ok to edit a file in this repository using the `Edit` button on Github if the change is simple enough. + +2. For significant changes (e.g not required for fixing typos), ensure that you have signed the [individual](https://rstudioblog.files.wordpress.com/2017/05/rstudio_individual_contributor_agreement.pdf) or [corporate](https://rstudioblog.files.wordpress.com/2017/05/rstudio_corporate_contributor_agreement.pdf) contributor agreement as appropriate. You can send the signed copy to . + +3. Submit the [pull request](https://help.github.com/articles/using-pull-requests). It is ok to submit as draft in your are still working on it but would like some feedback from us. It always good to share in the open that you are working on it. + +We'll try to be as responsive as possible in reviewing and accepting pull requests. Appreciate your contributions very much! diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml new file mode 100644 index 000000000..06aae5192 --- /dev/null +++ b/.github/workflows/pkgdown.yaml @@ -0,0 +1,88 @@ +on: + push: + branches: + - main + - master + pull_request: + branches: + - main + - master + +name: pkgdown + +jobs: + pkgdown: + if: ${{ github.event_name == 'push' || startsWith(github.head_ref, 'pkgdown') }} + runs-on: macos-latest + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + steps: + - uses: actions/checkout@v2 + + - uses: r-lib/actions/setup-r@v1 + id: install-r + + - uses: r-lib/actions/setup-pandoc@v1 + + - uses: r-lib/actions/setup-tinytex@v1 + env: + # install full prebuilt version + TINYTEX_INSTALLER: TinyTeX + + - name: Install pak and query dependencies + run: | + install.packages("pak", repos = "https://r-lib.github.io/p/pak/dev/") + saveRDS(pak::pkg_deps(".", dependencies = TRUE), ".github/r-depends.rds") + shell: Rscript {0} + + - name: Cache R packages + uses: actions/cache@v2 + with: + path: | + ${{ env.R_LIBS_USER }}/* + !${{ env.R_LIBS_USER }}/pak + key: macos-latest-${{ steps.install-r.outputs.installed-r-version }}-1-${{ hashFiles('.github/r-depends.rds') }} + restore-keys: macos-latest-${{ steps.install-r.outputs.installed-r-version }}-1- + + - name: Install package and dependencies + run: | + pak::local_install_dev_deps(upgrade = TRUE, dependencies = c("all", "Config/Needs/website")) + pak::pkg_install("r-lib/pkgdown") + pak::pkg_install("rstudio/quillt") + shell: Rscript {0} + + - name: Install package + run: R CMD INSTALL . + + - name: Cache some pkgdown assets + uses: actions/cache@v2 + with: + path: | + vignettes/articles/resources/*.gif + vignettes/articles/resources/*.pdf + vignettes/articles/cache/*.rds + key: ${{ hashFiles('vignettes/articles/_child_examples.Rmd') }}-1-${{ github.sha }} + restore-keys: | + ${{ hashFiles('vignettes/articles/_child_examples.Rmd') }}-1- + + + - name: Build pkgdown site + run: pkgdown::build_site(new_process = FALSE) + shell: Rscript {0} + + - name: Deploy to Netlify + id: netlify-deploy + uses: nwtgck/actions-netlify@v1.1 + with: + publish-dir: 'reference' + production-branch: master + github-token: ${{ secrets.GITHUB_TOKEN }} + deploy-message: + 'Deploy from GHA: ${{ github.event.head_commit.message }} (${{ github.sha }})' + enable-pull-request-comment: false + enable-commit-comment: false + enable-commit-status: true + alias: deploy-preview-${{ github.event.number }} + env: + NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} + NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }} diff --git a/.gitignore b/.gitignore index 7f6bab9e5..6a1c905da 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,5 @@ .Rhistory .RData *.log +reference +inst/doc diff --git a/DESCRIPTION b/DESCRIPTION index dbe67025b..bd0d36201 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -5,10 +5,11 @@ Version: 0.20.3 Authors@R: c( person("JJ", "Allaire", role = "aut", email = "jj@rstudio.com"), person("Yihui", "Xie", role = c("aut", "cre"), email = "xie@yihui.name", comment = c(ORCID = "0000-0003-0645-5666")), + person("Christophe", "Dervieux", role = c("aut"), email = "cderv@rstudio.com", comment = c(ORCID = "0000-0003-4474-2498")), + person(family = "RStudio", role = c("cph", "fnd")), person(family = "R Foundation", role = c("aut", "cph")), person("Hadley", "Wickham", role = "aut", email = "hadley@rstudio.com"), person(family = "Journal of Statistical Software", role = c("aut", "cph")), - person(family = "RStudio", role = "cph"), person("Ramnath ", "Vaidyanathan", role = c("aut", "cph"), email = "ramnath.vaidya@gmail.com"), person(family = "Association for Computing Machinery", role = c("aut", "cph")), person("Carl", "Boettiger", role = c("aut", "cph"), email = "cboettig@gmail.com"), @@ -44,7 +45,6 @@ Authors@R: c( person("Shixiang", "Wang", role = c("aut", "ctb"), email = "w_shixiang@163.com", comment = c(ORCID = "0000-0001-9855-7357")), person('Jay', 'Hesselberth', role = c('aut', 'ctb'), email = 'jay.hesselberth@gmail.com', comment = c(ORCID = '0000-0002-6299-179X')), person("Alfredo", "Hernández", role = c("ctb"), email = "aldomann.designs@gmail.com", comment = c(ORCID = "0000-0002-2660-4545")), - person("Christophe", "Dervieux", role = c("aut"), email = "cderv@rstudio.com", comment = c(ORCID = "0000-0003-4474-2498")), person("Stefano", "Coretta", role = c("ctb"), email = "stefano.coretta@gmail.com", comment = c(ORCID = "0000-0001-9627-5532", github = "stefanocoretta")), person("Alvaro", "Uzaheta", role = c("ctb"), email = "alvaro.uzaheta@gess.ethz.ch", comment = c(github = "auzaheta")) ) @@ -58,3 +58,5 @@ BugReports: https://github.com/rstudio/rticles/issues RoxygenNote: 7.1.1 Suggests: testit, bookdown, xtable Encoding: UTF-8 +VignetteBuilder: knitr +Config/Needs/website: magick, pdftools, gifski, rstudio/quillt diff --git a/NEWS.md b/NEWS.md index 3efba1be7..053d2e967 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,12 +1,10 @@ -rticles 0.21 ---------------------------------------------------------------------- +# rticles 0.21 -- Add the fenced div with id `#refs` in `frontier_article()` skeleton to place the reference section in the correct expected place (thanks, @graysonwhite, #423). +- Add the fenced div with id `#refs` in `frontiers_article()` skeleton to place the reference section in the correct expected place (thanks, @graysonwhite, #423). - `bioinformatics_article()` has no more trailing comma after last author (thanks, @stephenturner, #413). - `bioinformatics_article()` now separates `manuscript_type` (e.g., Applications note, Original article) and `subject_section` (e.g. Genome analysis, Phylogenetics) in template and skeleton (thanks, @stephenturner, #415) -rticles 0.20 ---------------------------------------------------------------------- +# rticles 0.20 - `lipics_article()` skeleton now sets option `bookdown.theorem.preamble` to FALSE to work with `bookdown::pdf_book()` and avoid conflicst in theorem environment definition. This requires **bookdown** 0.23 or higher (#392). @@ -26,8 +24,7 @@ rticles 0.20 - fix an issue with `rjournal_article()` template to insert newline in author's block only if a field exist (thanks, @huizezhang-sherry, #387) -rticles 0.19 ---------------------------------------------------------------------- +# rticles 0.19 - Update Copernicus Publications template to version 6.2 from 2021-01-15 (thanks, @RLumSK, #366). @@ -35,8 +32,7 @@ rticles 0.19 - Add article template `ims_article()` for *Institute of Mathematical Statistics* Journals, e.g., *Annals of Applied Statistics* (thanks, @auzaheta, #372) -rticles 0.18 ---------------------------------------------------------------------- +# rticles 0.18 - `springer_article()` now uses the yaml variable biblio-style to set bibliography style instead of bibstyle. (@eliocamp, #358) @@ -56,8 +52,7 @@ fix for the LaTeX problem sanitized with the last `rticles` update (thanks, @RLu - Add article template `jasa_article()` for the *Journal of the Acoustical Society of America* (JASA) (thanks, @stefanocoretta, #364) -rticles 0.17 ---------------------------------------------------------------------- +# rticles 0.17 - Fixes `arxiv_article()` template when adding graphics from code chunks (thanks, @Athanasiamo, #332). @@ -69,15 +64,13 @@ rticles 0.17 - Add article template `lipics_article()` for *Leibniz International Proceedings in Informatics* (LIPIcs) (thanks, @nuest, #288). -rticles 0.16 ---------------------------------------------------------------------- +# rticles 0.16 - Fixed `ctex_article()` to correctly use the default Pandoc template as intended in the PR #307, which introduced the bug #322 (thanks, @baketbek @cderv #323). - The minimal version of **knitr** required is 1.30 now. -rticles 0.15 ---------------------------------------------------------------------- +# rticles 0.15 - Added a new `journals()` function to list all available journal names in this package (#318). @@ -111,8 +104,7 @@ rticles 0.15 - Added the output format `rticles::ctex_article` as an alias to `rticles::ctex`, to be consistent with the names of other `*_article` formats. -rticles 0.14 ---------------------------------------------------------------------- +# rticles 0.14 - Added custom author ordering for the IEEE template (thanks, @DunLug, #263). @@ -124,8 +116,7 @@ rticles 0.14 - Added Oxford University Press (OUP) template (thanks, @dmkaplan2000, #271). -rticles 0.13 ---------------------------------------------------------------------- +# rticles 0.13 - Added the `cslreferences` environment to all templates (thanks, @bbauzile, #260). @@ -135,25 +126,21 @@ rticles 0.13 - Add support for bibliography styles on the Springer template (thanks, @swhaat, #262). -rticles 0.12 ---------------------------------------------------------------------- +# rticles 0.12 - Updated the `pnas_article()` document class from the PNAS website https://www.pnas.org/page/authors/latex (#21). -rticles 0.11 ---------------------------------------------------------------------- +# rticles 0.11 - Added the Journal of Open Source Software (and Education) template (@noamross, #229). - Tweaked the `tf_article` template to avoid using absolute full paths for figures in the "Figures" section (@jooyoungseo, #246). -rticles 0.10 ---------------------------------------------------------------------- +# rticles 0.10 - Support syntax highlighting in the `peerj_article()` format (@zkamvar, #238). -rticles 0.9 ---------------------------------------------------------------------- +# rticles 0.9 - Added support for Keywords in IEEE Trans template (@espinielli, #227). @@ -163,8 +150,7 @@ rticles 0.9 - Use csl file for citations in output format `elsevier_article()` (@nuest, #233). -rticles 0.8 ---------------------------------------------------------------------- +# rticles 0.8 - Added the Taylor & Francis journal template (@dleutnant, #218). @@ -174,8 +160,7 @@ rticles 0.8 - Updated the template for MDPI to 02/2019 (@dleutnant, #203). -rticles 0.7 ---------------------------------------------------------------------- +# rticles 0.7 - Added the template for the Frontiers Journals (@muschellij2, @zkamvar, #209). @@ -193,8 +178,7 @@ rticles 0.7 - The function `ctex_template()` was removed. If you need to use a custom LaTeX template for the `ctex` output format, just use the `template` option under `ctex`. -rticles 0.6 ---------------------------------------------------------------------- +# rticles 0.6 - Added the template for the SAGE Journals (thanks, @oguzhanogreden, #181). @@ -206,8 +190,7 @@ rticles 0.6 - Disabled syntax highlighting for `rjournal_article()` (thanks, @eddelbuettel, #185). -rticles 0.5 ---------------------------------------------------------------------- +# rticles 0.5 - Added the template for the IEEE Transaction Journals (thanks, @Emaasit, #97). @@ -231,20 +214,14 @@ rticles 0.5 - Supports breaking the JSS author list into multiple lines; see #100 for details. -rticles 0.4.1 ---------------------------------------------------------------------- +# rticles 0.4.1 - Add Royal Society Open Science journal template -rticles 0.2.0.9000 ---------------------------------------------------------------------- - - Add Institute of Electrical and Electronics Engineers (IEEE) IEEEtrans template for Conferences - -rticles 0.2 ---------------------------------------------------------------------- +# rticles 0.2 - Add American Chemical Society (ACS) template @@ -258,8 +235,6 @@ rticles 0.2 - Fix preamble variable name in R Journal template - -rticles 0.1 ---------------------------------------------------------------------- +# rticles 0.1 - Initial release to CRAN diff --git a/R/utils.R b/R/utils.R index f3397b871..7d2964465 100644 --- a/R/utils.R +++ b/R/utils.R @@ -15,11 +15,11 @@ #' @examples #' rticles::journals() journals <- function() { - sort(dir(pkg_file("rmarkdown", "templates"))) + sort(dir(pkg_file_template())) } find_resource <- function(template, file = 'template.tex') { - res <- pkg_file("rmarkdown", "templates", template, "resources", file) + res <- pkg_file_template(template, "resources", file) if (res == "") stop( "Couldn't find template file ", template, "/resources/", file, call. = FALSE ) @@ -86,6 +86,8 @@ get_list_element <- function(x, names) { pkg_file <- function(...) system.file(..., package = "rticles") +pkg_file_template <- function(...) pkg_file("rmarkdown", "templates", ...) + # utils for post processing tex files # correct authors field to the form "Author 1, Author 2, and Author 3" @@ -111,3 +113,22 @@ post_process_authors <- function(text) { # return modified text text } + + +# render a skeleton in a temp directory +render_draft <- function(journal, output_options = NULL, quiet = FALSE) { + dir <- tempfile() + dir.create(dir) + oldwd <- setwd(dir) + on.exit(setwd(oldwd), add = TRUE) + # create a draft of the format + doc <- paste0(journal,"_article",".Rmd") + rmarkdown::draft(doc, template = journal, package = "rticles", create_dir = FALSE, edit = FALSE) + # render the file in the temp dir + message('Rendering the ', journal, ' format...', + if (!is.null(output_options)) " (with output options)") + output_file <- xfun::Rscript_call( + fun = rmarkdown::render, + args = list(doc, output_options = output_options, quiet = quiet) + ) +} diff --git a/README.Rmd b/README.Rmd new file mode 100644 index 000000000..7829cce1d --- /dev/null +++ b/README.Rmd @@ -0,0 +1,123 @@ +--- +output: github_document +--- + + + + + +[![R-CMD-check](https://github.com/rstudio/rticles/workflows/R-CMD-check/badge.svg)](https://github.com/rstudio/rticles/actions) [![Downloads from the RStudio CRAN mirror](https://cranlogs.r-pkg.org/badges/rticles)](https://cran.r-project.org/package=rticles) [![CRAN status](https://www.r-pkg.org/badges/version/rticles)](https://CRAN.R-project.org/package=rticles) + + + +# rticles + +The **rticles** package provides a suite of custom [R Markdown](https://rmarkdown.rstudio.com) LaTeX formats and templates for various formats. Most of the templates are provided and maintained by the community, and anyone can contribute a new template. See [How to contribute](#how-to-contribute) below. + +## Book + +R Markdown: The Definitive Guide + +## Installation + +You can install and use **rticles** from CRAN as follows: + +``` r +install.packages("rticles") +``` + +If you wish to install the development version from GitHub (which often contains new article formats), you can do this: + +``` r +remotes::install_github("rstudio/rticles") +``` + +## Using rticles + +```{r child="vignettes/usage.md"} +``` + +## Templates + +Currently included templates and their contributors are the following: + +| Journal | Contributors | Pull request | Output format| +|-|-|-|-| +| [ACM: Association for Computings Machinery](https://www.acm.org/publications/about-publications) | [\@ramnathv](https://github.com/ramnathv)| [\#8](https://github.com/rstudio/rticles/pull/8) | `acm_article()`| +| [ACS](https://pubs.acs.org) | [\@yufree](https://github.com/yufree)| [\#15](https://github.com/rstudio/rticles/pull/15) | `acs_article()`| +| [AEA: American Economic Association](https://www.aeaweb.org/journals/policies/templates)| [\@sboysel](https://github.com/sboysel)| [\#86](https://github.com/rstudio/rticles/pull/86) | `aea_articles()` | +| [AGU](https://agupubs.onlinelibrary.wiley.com/) | [\@eliocamp](https://github.com/eliocamp)| [\#199](https://github.com/rstudio/rticles/pull/99)| `agu_article()`| +| [AMS: American Meteorological Society](https://www.ametsoc.org/)| [\@yufree](https://github.com/yufree)| [\#96](https://github.com/rstudio/rticles/pull/96) | `ams_article()`| +| [ASA: American Statistical Association](https://www.amstat.org/)|| [\#111](https://github.com/rstudio/rticles/pull/111) | `asa_article()`| +| [arXiv](https://arxiv.org/) pre-prints based on George Kour's template| [\@alexpghayes](https://github.com)| [\#236](https://github.com/rstudio/rticles/pull/236) | `arxiv_article()`| +| [Bioinformatics](https://academic.oup.com/bioinformatics) | [\@ShixiangWang](https://github.com/ShixiangWang)| [\#297](https://github.com/rstudio/rticles/pull/297) | `bioinformatics_article()` | +| [Biometrics](https://biometrics.biometricsociety.org) | [\@daltonhance](https://github.com/daltonhance)| [\#170](https://github.com/rstudio/rticles/pull/170) | `biometrics_article()` | +| [Bulletin de l'AMQ](https://www.amq.math.ca/bulletin/)| [\@desautm](https://github.com/desautm)| [\#145](https://github.com/rstudio/rticles/pull/145) | `amq_article()`| +| [Copernicus Publications](https://publications.copernicus.org)| [\@nuest](https://github.com/nuest), [\@RLumSK](https://github.com/RLumSK) | [\#172](https://github.com/rstudio/rticles/pull/172), [\#342](https://github.com/rstudio/rticles/pull/342) | `copernicus_article()` | +| [CTeX](https://ctan.org/pkg/ctex) ||| `ctex()` | +| [Elsevier](https://www.elsevier.com)| [\@cboettig](https://github.com/cboettig)| [\#27](https://github.com/rstudio/rticles/pull/27) | `elsevier_article()` | +| [Frontiers](https://www.frontiersin.org/) | [\@muschellij2](https://github.com/muschellij2)| [\#211](https://github.com/rstudio/rticles/pull/211) | `frontiers_article()`| +| [IEEE Transaction](http://www.ieee.org/publications_standards/publications/authors/author_templates.html) | [\@Emaasit](https://github.com/Emaasit), [\@espinielli](https://github.com/espinielli), [\@nathanweeks](https://github.com/nathanweeks), [\@DunLug](https://github.com/DunLug) | [\#97](https://github.com/rstudio/rticles/pull/97), [\#169](https://github.com/rstudio/rticles/pull/169), [\#227](https://github.com/rstudio/rticles/pull/227), [\#263](https://github.com/rstudio/rticles/pull/263), [\#264](https://github.com/rstudio/rticles/pull/264), [\#265](https://github.com/rstudio/rticles/pull/265) | `ieee_article()` | +| [IMS: Institute of Mathematical Statistics](https://imstat.org/) [AoAS: Annals of Applied Statistics](https://imstat.org/journals-and-publications/annals-of-applied-statistics/) | [\@auzaheta](https://github.com/auzaheta)| [\#372](https://github.com/rstudio/rticles/pull/372) | `ims_article()`| +| [JASA: Journal of the Acoustical Society of America](https://asa.scitation.org/journal/jas) | [\@stefanocoretta](https://github.com/stefanocoretta)| [\#364](https://github.com/rstudio/rticles/pull/364) | `jasa_article()` | +| [JOSS: Journal of Open Source Software](https://joss.theoj.org/) [JOSE: Journal of Open Source Education](https://jose.theoj.org/)| [\@noamross](https://github.com/noamross)| [\#229](https://github.com/rstudio/rticles/pull/229) | `joss_article()` | +| [JSS: Journal of Statistical Software](https://www.jstatsoft.org) ||| `jss_article()`| +| [LIPIcs](https://www.dagstuhl.de/en/publications/lipics)| [\@nuest](https://github.com/nuest)| [\#288](https://github.com/rstudio/rticles/pull/288) | `lipics_article()` | +| [MDPI](https://www.mdpi.com)| [\@dleutnant](https://github.com/dleutnant)| [\#147](https://github.com/rstudio/rticles/pull/147) | `mdpi_article()` | +| [MNRAS: Monthly Notices of the Royal Astronomical Society](https://academic.oup.com/mnras)| [\@oleskiewicz](https://github.com/oleskiewicz)| [\#175](https://github.com/rstudio/rticles/pull/175) | `mnras_article()`| +| [OUP: Oxford University Press](https://academic.oup.com/journals/pages/authors/preparing_your_manuscript) | [\@dmkaplan](https://github.com/dmkaplan)| [\#284](https://github.com/rstudio/rticles/pull/284) | `oup_articles()` | +| [PeerJ: Journal of Life and Environmental Sciences](https://peerj.com)| [\@zkamvar](https://github.com/zkamvar)| [\#127](https://github.com/rstudio/rticles/pull/127) | `peerj_article()`| +| [PiHPh: Papers in Historical Phonology](http://journals.ed.ac.uk/pihph/about/submissions) | [\@stefanocoretta](https://github.com/stefanocoretta)| [\#362](https://github.com/rstudio/rticles/pull/362) | `pihph_article()`| +| [PLOS](https://plos.org/#journals)| [\@sjmgarnier](https://github.com/sjmgarnier)| [\#12](https://github.com/rstudio/rticles/pull/12) | `plos_article()` | +| [PNAS: Proceedings of the National Academy of Sciences](https://www.pnas.org/)| [\@cboettig](https://github.com/cboettig)| [\#72](https://github.com/rstudio/rticles/pull/72) | `pnas_article()` | +| [RSOS: Royal Society Open Science](https://www.royalsocietypublishing.org/journal/rsos) | [\@ThierryO](https://github.com/ThierryO)| [\#135](https://github.com/rstudio/rticles/pull/135) | `rsos_article()` | +| [RSS: Royal Statistical Society](https://rss.org.uk/) | [\@carlganz](https://github.com/carlganz)| [\#110](https://github.com/rstudio/rticles/pull/110) | `rss_article()`| +| [Sage](https://uk.sagepub.com/en-gb/eur/manuscript-submission-guidelines) | [\@oguzhanogreden](https://github.com/oguzhanogreden)| [\#181](https://github.com/rstudio/rticles/pull/181) | `sage_article()` | +| [Springer](https://www.springer.com/gp/livingreviews/latex-templates) | [\@strakaps](https://github.com/strakaps)| [\#164](https://github.com/rstudio/rticles/pull/164) | `springer_article()` | +| [SIM: Statistics in Medicine](https://onlinelibrary.wiley.com/journal/10970258) | [\@ellessenne](https://github.com/ellessenne)| [\#231](https://github.com/rstudio/rticles/pull/231) | `sim_article()`| +| [Taylor & Francis](https://www.tandfonline.com/)| [\@dleutnant](https://github.com/dleutnant)| [\#218](https://github.com/rstudio/rticles/pull/218) | `tf_article()` | +| [The R Journal](https://journal.r-project.org/) ||| `rjournal_article()` | + +You can also get the list of available journal names with `rticles::journals()`. + +Under the hood, LaTeX templates are used to ensure that documents conform precisely to submission standards. At the same time, composition and formatting can be done using lightweight [markdown](https://rmarkdown.rstudio.com/authoring_basics.html) syntax, and R code and its output can be seamlessly included using [knitr](https://yihui.org/knitr/). + +## Getting help + +There are two main places to get help: + +1. The [RStudio community](https://community.rstudio.com/tags/c/R-Markdown/10/rticles) is a friendly place to ask any questions about **rticles**. Be sure to use the `rticles` tag. + +2. [Stack Overflow](https://stackoverflow.com/questions/tagged/rticles) is a great source of answers to common **bookdown** questions. Use the tags [`[r][rticles]`](https://stackoverflow.com/questions/tagged/rticles+r) if you ask a question. + +## Code of Conduct + +Please note that the rticles project is released with a [Contributor Code of Conduct](https://pkgs.rstudio.com/rticles/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. + +## How to contribute? + +Most of the templates are contributed directly by the users in the community. If you want **rticles** to offer a new journal format, you can contribute by the following way. + +### Suggest an idea for new format opening an issue. + +You may not feel confident enough or may not have time to contribute a new format. By opening a new issue, you can share the idea for this format, and see if someone in the community can help on it. +This is not the best way to quickly get your format included but at least it is a great way to see if others are insterested too. + +To see the existing suggested formats, just filter issues with the [help wanted](https://github.com/rstudio/rticles/labels/help%20wanted) label. You can then add a :+1: or help to add the template :wink:. + +### Contribute a new template format opening a pull request. + +To contribute a new format, you need to open a new pull request (PR). When opening the PR, you'll see the [PR template](https://github.com/rstudio/rticles/blob/master/.github/PULL_REQUEST_TEMPLATE.md) explaining how to proceed and what is important to check. Please follow it. +Even if you are just starting or you are not finished, you share your work by creating a [draft PR](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests). It is a great way to let us know that you are still working on it (like [these opened ones](https://github.com/rstudio/rticles/pulls?q=is%3Apr+draft%3Atrue+)), and it is also a great way to ask for help from the community. +When you are ready, you can submit the PR for review, and we will iterate until it is merged. + +#### Technical resources helpful to contribute a template + +The best way to get started is to look at the previous examples of submitted PR. You'll find links to them in the table [above](#overview). + +All the `rticles` format are build similarly by providing a new pandoc tex template to replace the default one. You'll learn more about pandoc templates in these places: + +- [R Markdown Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/latex-template.html) +- [The Pandoc manual](https://pandoc.org/MANUAL.html#templates) + +You can study [existing formats](inst/rmarkdown/templates) to see how all this works. diff --git a/README.md b/README.md index 5dc3cbefc..7476e1e77 100644 --- a/README.md +++ b/README.md @@ -1,123 +1,187 @@ + + + [![R-CMD-check](https://github.com/rstudio/rticles/workflows/R-CMD-check/badge.svg)](https://github.com/rstudio/rticles/actions) -[![Downloads from the RStudio CRAN mirror](https://cranlogs.r-pkg.org/badges/rticles)](https://cran.r-project.org/package=rticles) -[![CRAN status](https://www.r-pkg.org/badges/version/rticles)](https://CRAN.R-project.org/package=rticles) +[![Downloads from the RStudio CRAN +mirror](https://cranlogs.r-pkg.org/badges/rticles)](https://cran.r-project.org/package=rticles) +[![CRAN +status](https://www.r-pkg.org/badges/version/rticles)](https://CRAN.R-project.org/package=rticles) + +# rticles + +The **rticles** package provides a suite of custom [R +Markdown](https://rmarkdown.rstudio.com) LaTeX formats and templates for +various formats. Most of the templates are provided and maintained by +the community, and anyone can contribute a new template. See [How to +contribute](#how-to-contribute) below. + +## Book + +R Markdown: The Definitive Guide + ## Installation You can install and use **rticles** from CRAN as follows: -```r +``` r install.packages("rticles") ``` -If you wish to install the development version from GitHub (which often contains new article formats), you can do this: +If you wish to install the development version from GitHub (which often +contains new article formats), you can do this: -```r +``` r remotes::install_github("rstudio/rticles") ``` -## Overview - -The **rticles** package provides a suite of custom [R Markdown](https://rmarkdown.rstudio.com) LaTeX formats and templates for various formats. Most of the templates are provided and maintained by the community, and anyone can contribute a new template. See [How to contribute](#how-to-contribute) below. - -Currently included templates and their contributors are the following: - -| Journal | Contributors | Pull request | Output format | -|-|-|-|-| -| [ACM: Association for Computing Machinery](https://www.acm.org/publications/about-publications) | [@ramnathv](https://github.com/ramnathv) | [#8](https://github.com/rstudio/rticles/pull/8) | `acm_article()` | -| [ACS](https://pubs.acs.org) | [@yufree](https://github.com/yufree) | [#15](https://github.com/rstudio/rticles/pull/15) | `acs_article()` | -| [AEA: American Economic Association](https://www.aeaweb.org/journals/policies/templates) | [@sboysel](https://github.com/sboysel) | [#86](https://github.com/rstudio/rticles/pull/86) | `aea_articles()` | -| [AGU](https://agupubs.onlinelibrary.wiley.com/) | [@eliocamp](https://github.com/eliocamp) | [#199](https://github.com/rstudio/rticles/pull/99) | `agu_article()` | -| [AMS: American Meteorological Society](https://www.ametsoc.org/) | [@yufree](https://github.com/yufree) | [#96](https://github.com/rstudio/rticles/pull/96) | `ams_article()` | -| [ASA: American Statistical Association](https://www.amstat.org/) | | [#111](https://github.com/rstudio/rticles/pull/111) | `asa_article()` | -| [arXiv](https://arxiv.org/) pre-prints based on George Kour's template | [@alexpghayes](https://github.com) | [#236](https://github.com/rstudio/rticles/pull/236) | `arxiv_article()` | -| [Bioinformatics](https://academic.oup.com/bioinformatics) | [@ShixiangWang](https://github.com/ShixiangWang) | [#297](https://github.com/rstudio/rticles/pull/297) | `bioinformatics_article()` | -| [Biometrics](https://biometrics.biometricsociety.org) | [@daltonhance](https://github.com/daltonhance) | [#170](https://github.com/rstudio/rticles/pull/170) | `biometrics_article()` | -| [Bulletin de l'AMQ](https://www.amq.math.ca/bulletin/) | [@desautm](https://github.com/desautm) | [#145](https://github.com/rstudio/rticles/pull/145) | `amq_article()` | -| [Copernicus Publications](https://publications.copernicus.org) | [@nuest](https://github.com/nuest), [@RLumSK](https://github.com/RLumSK) | [#172](https://github.com/rstudio/rticles/pull/172), [#342](https://github.com/rstudio/rticles/pull/342) | `copernicus_article()` | -| [CTeX](https://ctan.org/pkg/ctex) | | | `ctex()` | -| [Elsevier](https://www.elsevier.com) | [@cboettig](https://github.com/cboettig) | [#27](https://github.com/rstudio/rticles/pull/27) | `elsevier_article()` | -| [Frontiers](https://www.frontiersin.org/) | [@muschellij2](https://github.com/muschellij2) | [#211](https://github.com/rstudio/rticles/pull/211) | `frontiers_article()` | -| [IEEE Transaction](http://www.ieee.org/publications_standards/publications/authors/author_templates.html) | [@Emaasit](https://github.com/Emaasit), [@espinielli](https://github.com/espinielli), [@nathanweeks](https://github.com/nathanweeks), [@DunLug](https://github.com/DunLug) | [#97](https://github.com/rstudio/rticles/pull/97), [#169](https://github.com/rstudio/rticles/pull/169), [#227](https://github.com/rstudio/rticles/pull/227), [#263](https://github.com/rstudio/rticles/pull/263), [#264](https://github.com/rstudio/rticles/pull/264), [#265](https://github.com/rstudio/rticles/pull/265) | `ieee_article()` | -| [IMS: Institute of Mathematical Statistics](https://imstat.org/) [AoAS: Annals of Applied Statistics](https://imstat.org/journals-and-publications/annals-of-applied-statistics/) | [@auzaheta](https://github.com/auzaheta) | [#372](https://github.com/rstudio/rticles/pull/372) | `ims_article()` | -| [JASA: Journal of the Acoustical Society of America](https://asa.scitation.org/journal/jas) | [@stefanocoretta](https://github.com/stefanocoretta) | [#364](https://github.com/rstudio/rticles/pull/364) | `jasa_article()` | -| [JOSS: Journal of Open Source Software](https://joss.theoj.org/) [JOSE: Journal of Open Source Education](https://jose.theoj.org/) | [@noamross](https://github.com/noamross) | [#229](https://github.com/rstudio/rticles/pull/229) | `joss_article()` | -| [JSS: Journal of Statistical Software](https://www.jstatsoft.org) | | | `jss_article()` | -| [LIPIcs](https://www.dagstuhl.de/en/publications/lipics) | [@nuest](https://github.com/nuest) | [#288](https://github.com/rstudio/rticles/pull/288) | `lipics_article()` | -| [MDPI](https://www.mdpi.com) | [@dleutnant](https://github.com/dleutnant) | [#147](https://github.com/rstudio/rticles/pull/147) | `mdpi_article()` | -| [MNRAS: Monthly Notices of the Royal Astronomical Society](https://academic.oup.com/mnras) | [@oleskiewicz](https://github.com/oleskiewicz) | [#175](https://github.com/rstudio/rticles/pull/175) | `mnras_article()` | -| [OUP: Oxford University Press](https://academic.oup.com/journals/pages/authors/preparing_your_manuscript) | [@dmkaplan](https://github.com/dmkaplan) | [#284](https://github.com/rstudio/rticles/pull/284) | `oup_articles()` | -| [PeerJ: Journal of Life and Environmental Sciences](https://peerj.com) | [@zkamvar](https://github.com/zkamvar) | [#127](https://github.com/rstudio/rticles/pull/127) | `peerj_article()` | -| [PiHPh: Papers in Historical Phonology](http://journals.ed.ac.uk/pihph/about/submissions) | [@stefanocoretta](https://github.com/stefanocoretta) | [#362](https://github.com/rstudio/rticles/pull/362) | `pihph_article()` | -| [PLOS](https://plos.org/#journals) | [@sjmgarnier](https://github.com/sjmgarnier) | [#12](https://github.com/rstudio/rticles/pull/12) | `plos_article()` | -| [PNAS: Proceedings of the National Academy of Sciences](https://www.pnas.org/) | [@cboettig](https://github.com/cboettig) | [#72](https://github.com/rstudio/rticles/pull/72) | `pnas_article()` | -| [RSOS: Royal Society Open Science](https://www.royalsocietypublishing.org/journal/rsos) | [@ThierryO](https://github.com/ThierryO) | [#135](https://github.com/rstudio/rticles/pull/135) | `rsos_article()` | -| [RSS: Royal Statistical Society](https://rss.org.uk/) | [@carlganz](https://github.com/carlganz) | [#110](https://github.com/rstudio/rticles/pull/110) | `rss_article()` | -| [Sage](https://uk.sagepub.com/en-gb/eur/manuscript-submission-guidelines) | [@oguzhanogreden](https://github.com/oguzhanogreden) | [#181](https://github.com/rstudio/rticles/pull/181) | `sage_article()` | -| [Springer](https://www.springer.com/gp/livingreviews/latex-templates) | [@strakaps](https://github.com/strakaps) | [#164](https://github.com/rstudio/rticles/pull/164) | `springer_article()` | -| [SIM: Statistics in Medicine](https://onlinelibrary.wiley.com/journal/10970258) | [@ellessenne](https://github.com/ellessenne) | [#231](https://github.com/rstudio/rticles/pull/231) | `sim_article()` | -| [Taylor & Francis](https://www.tandfonline.com/) | [@dleutnant](https://github.com/dleutnant) | [#218](https://github.com/rstudio/rticles/pull/218) | `tf_article()` | -| [The R Journal](https://journal.r-project.org/) | | | `rjournal_article()` | +## Using rticles +To use **rticles** from RStudio, you can access the templates through +`File -> New File -> R Markdown`. This will open the dialog box where +you can select from one of the available templates: -You can also get the list of available journal names with `rticles::journals()`. +![New R +Markdown](https://bookdown.org/yihui/rmarkdown/images/rticles-templates.png) -Under the hood, LaTeX templates are used to ensure that documents conform precisely to submission standards. At the same time, composition and formatting can be done using lightweight [markdown](https://rmarkdown.rstudio.com/authoring_basics.html) syntax, and R code and its output can be seamlessly included using [knitr](https://yihui.org/knitr/). +If you are not using RStudio, you’ll also need to install +[Pandoc](https://pandoc.org) following these +[instructions](https://bookdown.org/yihui/rmarkdown-cookbook/install-pandoc.html). +Then, use the `rmarkdown::draft()` function to create articles: -Using **rticles** requires the prerequisites described below. You can get most of these automatically by installing the latest release of RStudio (instructions for using **rticles** without RStudio are also provided). - -## Using rticles from RStudio - -To use **rticles** from RStudio: - -1. Install the latest [RStudio](https://rstudio.com/products/rstudio/download/). - -2. Install the **rticles** package. - -3. Use the **New R Markdown** dialog to create an article from one of the templates: - - ![New R Markdown](https://rmarkdown.rstudio.com/images/new_r_markdown.png) - -## Using rticles outside of RStudio - -1. Install [Pandoc](https://pandoc.org) using the [instructions for your platform](https://rmarkdown.rstudio.com/docs/articles/pandoc.html). - -2. Install the **rticles** packages. +``` r +rmarkdown::draft( + "MyJSSArticle.Rmd", template = "jss", package = "rticles" +) +rmarkdown::draft( + "MyRJournalArticle", template = "rjournal", package = "rticles" +) +``` -3. Use the `rmarkdown::draft()` function to create articles: +This will create a folder containing a Rmd file using the corresponding +output format and all the assets required by this format. - ```r - rmarkdown::draft("MyJSSArticle.Rmd", template = "jss", package = "rticles") - rmarkdown::draft("MyRJournalArticle", template = "rjournal", package = "rticles") - ``` - This will create a folder containing a Rmd file using the corresponding output format and all the assets required by this format. +## Templates -## How to contribute? +Currently included templates and their contributors are the following: -Most of the templates are contributed directly by the users in the community. If you want **rticles** to offer a new journal format, you can contribute by the following way. +| Journal | Contributors | Pull request | Output format | +|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------| +| [ACM: Association for Computings Machinery](https://www.acm.org/publications/about-publications) | [@ramnathv](https://github.com/ramnathv) | [#8](https://github.com/rstudio/rticles/pull/8) | `acm_article()` | +| [ACS](https://pubs.acs.org) | [@yufree](https://github.com/yufree) | [#15](https://github.com/rstudio/rticles/pull/15) | `acs_article()` | +| [AEA: American Economic Association](https://www.aeaweb.org/journals/policies/templates) | [@sboysel](https://github.com/sboysel) | [#86](https://github.com/rstudio/rticles/pull/86) | `aea_articles()` | +| [AGU](https://agupubs.onlinelibrary.wiley.com/) | [@eliocamp](https://github.com/eliocamp) | [#199](https://github.com/rstudio/rticles/pull/99) | `agu_article()` | +| [AMS: American Meteorological Society](https://www.ametsoc.org/) | [@yufree](https://github.com/yufree) | [#96](https://github.com/rstudio/rticles/pull/96) | `ams_article()` | +| [ASA: American Statistical Association](https://www.amstat.org/) | | [#111](https://github.com/rstudio/rticles/pull/111) | `asa_article()` | +| [arXiv](https://arxiv.org/) pre-prints based on George Kour’s template | [@alexpghayes](https://github.com) | [#236](https://github.com/rstudio/rticles/pull/236) | `arxiv_article()` | +| [Bioinformatics](https://academic.oup.com/bioinformatics) | [@ShixiangWang](https://github.com/ShixiangWang) | [#297](https://github.com/rstudio/rticles/pull/297) | `bioinformatics_article()` | +| [Biometrics](https://biometrics.biometricsociety.org) | [@daltonhance](https://github.com/daltonhance) | [#170](https://github.com/rstudio/rticles/pull/170) | `biometrics_article()` | +| [Bulletin de l’AMQ](https://www.amq.math.ca/bulletin/) | [@desautm](https://github.com/desautm) | [#145](https://github.com/rstudio/rticles/pull/145) | `amq_article()` | +| [Copernicus Publications](https://publications.copernicus.org) | [@nuest](https://github.com/nuest), [@RLumSK](https://github.com/RLumSK) | [#172](https://github.com/rstudio/rticles/pull/172), [#342](https://github.com/rstudio/rticles/pull/342) | `copernicus_article()` | +| [CTeX](https://ctan.org/pkg/ctex) | | | `ctex()` | +| [Elsevier](https://www.elsevier.com) | [@cboettig](https://github.com/cboettig) | [#27](https://github.com/rstudio/rticles/pull/27) | `elsevier_article()` | +| [Frontiers](https://www.frontiersin.org/) | [@muschellij2](https://github.com/muschellij2) | [#211](https://github.com/rstudio/rticles/pull/211) | `frontiers_article()` | +| [IEEE Transaction](http://www.ieee.org/publications_standards/publications/authors/author_templates.html) | [@Emaasit](https://github.com/Emaasit), [@espinielli](https://github.com/espinielli), [@nathanweeks](https://github.com/nathanweeks), [@DunLug](https://github.com/DunLug) | [#97](https://github.com/rstudio/rticles/pull/97), [#169](https://github.com/rstudio/rticles/pull/169), [#227](https://github.com/rstudio/rticles/pull/227), [#263](https://github.com/rstudio/rticles/pull/263), [#264](https://github.com/rstudio/rticles/pull/264), [#265](https://github.com/rstudio/rticles/pull/265) | `ieee_article()` | +| [IMS: Institute of Mathematical Statistics](https://imstat.org/) [AoAS: Annals of Applied Statistics](https://imstat.org/journals-and-publications/annals-of-applied-statistics/) | [@auzaheta](https://github.com/auzaheta) | [#372](https://github.com/rstudio/rticles/pull/372) | `ims_article()` | +| [JASA: Journal of the Acoustical Society of America](https://asa.scitation.org/journal/jas) | [@stefanocoretta](https://github.com/stefanocoretta) | [#364](https://github.com/rstudio/rticles/pull/364) | `jasa_article()` | +| [JOSS: Journal of Open Source Software](https://joss.theoj.org/) [JOSE: Journal of Open Source Education](https://jose.theoj.org/) | [@noamross](https://github.com/noamross) | [#229](https://github.com/rstudio/rticles/pull/229) | `joss_article()` | +| [JSS: Journal of Statistical Software](https://www.jstatsoft.org) | | | `jss_article()` | +| [LIPIcs](https://www.dagstuhl.de/en/publications/lipics) | [@nuest](https://github.com/nuest) | [#288](https://github.com/rstudio/rticles/pull/288) | `lipics_article()` | +| [MDPI](https://www.mdpi.com) | [@dleutnant](https://github.com/dleutnant) | [#147](https://github.com/rstudio/rticles/pull/147) | `mdpi_article()` | +| [MNRAS: Monthly Notices of the Royal Astronomical Society](https://academic.oup.com/mnras) | [@oleskiewicz](https://github.com/oleskiewicz) | [#175](https://github.com/rstudio/rticles/pull/175) | `mnras_article()` | +| [OUP: Oxford University Press](https://academic.oup.com/journals/pages/authors/preparing_your_manuscript) | [@dmkaplan](https://github.com/dmkaplan) | [#284](https://github.com/rstudio/rticles/pull/284) | `oup_articles()` | +| [PeerJ: Journal of Life and Environmental Sciences](https://peerj.com) | [@zkamvar](https://github.com/zkamvar) | [#127](https://github.com/rstudio/rticles/pull/127) | `peerj_article()` | +| [PiHPh: Papers in Historical Phonology](http://journals.ed.ac.uk/pihph/about/submissions) | [@stefanocoretta](https://github.com/stefanocoretta) | [#362](https://github.com/rstudio/rticles/pull/362) | `pihph_article()` | +| [PLOS](https://plos.org/#journals) | [@sjmgarnier](https://github.com/sjmgarnier) | [#12](https://github.com/rstudio/rticles/pull/12) | `plos_article()` | +| [PNAS: Proceedings of the National Academy of Sciences](https://www.pnas.org/) | [@cboettig](https://github.com/cboettig) | [#72](https://github.com/rstudio/rticles/pull/72) | `pnas_article()` | +| [RSOS: Royal Society Open Science](https://www.royalsocietypublishing.org/journal/rsos) | [@ThierryO](https://github.com/ThierryO) | [#135](https://github.com/rstudio/rticles/pull/135) | `rsos_article()` | +| [RSS: Royal Statistical Society](https://rss.org.uk/) | [@carlganz](https://github.com/carlganz) | [#110](https://github.com/rstudio/rticles/pull/110) | `rss_article()` | +| [Sage](https://uk.sagepub.com/en-gb/eur/manuscript-submission-guidelines) | [@oguzhanogreden](https://github.com/oguzhanogreden) | [#181](https://github.com/rstudio/rticles/pull/181) | `sage_article()` | +| [Springer](https://www.springer.com/gp/livingreviews/latex-templates) | [@strakaps](https://github.com/strakaps) | [#164](https://github.com/rstudio/rticles/pull/164) | `springer_article()` | +| [SIM: Statistics in Medicine](https://onlinelibrary.wiley.com/journal/10970258) | [@ellessenne](https://github.com/ellessenne) | [#231](https://github.com/rstudio/rticles/pull/231) | `sim_article()` | +| [Taylor & Francis](https://www.tandfonline.com/) | [@dleutnant](https://github.com/dleutnant) | [#218](https://github.com/rstudio/rticles/pull/218) | `tf_article()` | +| [The R Journal](https://journal.r-project.org/) | | | `rjournal_article()` | + +You can also get the list of available journal names with +`rticles::journals()`. + +Under the hood, LaTeX templates are used to ensure that documents +conform precisely to submission standards. At the same time, composition +and formatting can be done using lightweight +[markdown](https://rmarkdown.rstudio.com/authoring_basics.html) syntax, +and R code and its output can be seamlessly included using +[knitr](https://yihui.org/knitr/). + +## Getting help + +There are two main places to get help: + +1. The [RStudio + community](https://community.rstudio.com/tags/c/R-Markdown/10/rticles) + is a friendly place to ask any questions about **rticles**. Be sure + to use the `rticles` tag. + +2. [Stack Overflow](https://stackoverflow.com/questions/tagged/rticles) + is a great source of answers to common **bookdown** questions. Use + the tags + [`[r][rticles]`](https://stackoverflow.com/questions/tagged/rticles+r) + if you ask a question. + +## Code of Conduct + +Please note that the rticles project is released with a [Contributor +Code of Conduct](https://pkgs.rstudio.com/rticles/CODE_OF_CONDUCT.html). +By contributing to this project, you agree to abide by its terms. + +## How to contribute? + +Most of the templates are contributed directly by the users in the +community. If you want **rticles** to offer a new journal format, you +can contribute by the following way. ### Suggest an idea for new format opening an issue. -You may not feel confident enough or may not have time to contribute a new format. By opening a new issue, you can share the idea for this format, and see if someone in the community can help on it. -This is not the best way to quickly get your format included but at least it is a great way to see if others are insterested too. +You may not feel confident enough or may not have time to contribute a +new format. By opening a new issue, you can share the idea for this +format, and see if someone in the community can help on it. +This is not the best way to quickly get your format included but at +least it is a great way to see if others are insterested too. -To see the existing suggested formats, just filter issues with the [help wanted](https://github.com/rstudio/rticles/labels/help%20wanted) label. You can then add a :+1: or help to add the template :wink:. +To see the existing suggested formats, just filter issues with the [help +wanted](https://github.com/rstudio/rticles/labels/help%20wanted) label. +You can then add a :+1: or help to add the template :wink:. ### Contribute a new template format opening a pull request. -To contribute a new format, you need to open a new pull request (PR). When opening the PR, you'll see the [PR template](https://github.com/rstudio/rticles/blob/master/.github/PULL_REQUEST_TEMPLATE.md) explaining how to proceed and what is important to check. Please follow it. -Even if you are just starting or you are not finished, you share your work by creating a [draft PR](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests). It is a great way to let us know that you are still working on it (like [these opened ones](https://github.com/rstudio/rticles/pulls?q=is%3Apr+draft%3Atrue+)), and it is also a great way to ask for help from the community. -When you are ready, you can submit the PR for review, and we will iterate until it is merged. +To contribute a new format, you need to open a new pull request (PR). +When opening the PR, you’ll see the [PR +template](https://github.com/rstudio/rticles/blob/master/.github/PULL_REQUEST_TEMPLATE.md) +explaining how to proceed and what is important to check. Please follow +it. +Even if you are just starting or you are not finished, you share your +work by creating a [draft +PR](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests). +It is a great way to let us know that you are still working on it (like +[these opened +ones](https://github.com/rstudio/rticles/pulls?q=is%3Apr+draft%3Atrue+)), +and it is also a great way to ask for help from the community. +When you are ready, you can submit the PR for review, and we will +iterate until it is merged. #### Technical resources helpful to contribute a template -The best way to get started is to look at the previous examples of submitted PR. You'll find links to them in the table [above](#overview). +The best way to get started is to look at the previous examples of +submitted PR. You’ll find links to them in the table [above](#overview). -All the `rticles` format are build similarly by providing a new pandoc tex template to replace the default one. You'll learn more about pandoc templates in these places: +All the `rticles` format are build similarly by providing a new pandoc +tex template to replace the default one. You’ll learn more about pandoc +templates in these places: -* [R Markdown Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/latex-template.html) -* [The Pandoc manual](https://pandoc.org/MANUAL.html#templates) +- [R Markdown + Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/latex-template.html) +- [The Pandoc manual](https://pandoc.org/MANUAL.html#templates) -You can study [existing formats](inst/rmarkdown/templates) to see how all this works. +You can study [existing formats](inst/rmarkdown/templates) to see how +all this works. diff --git a/_pkgdown.yml b/_pkgdown.yml new file mode 100644 index 000000000..e7c39dc34 --- /dev/null +++ b/_pkgdown.yml @@ -0,0 +1,68 @@ +destination: reference + +# website will be referenced on https://pkgs.rstudio.com/ +# Open a PR in https://github.com/rstudio/pkgs.rstudio.com +url: https://pkgs.rstudio.com/rticles/ + +template: + package: quillt + opengraph: + image: + src: man/figures/logo.png + alt: "rticles package" + twitter: + creator: "@rstudio" + card: summary + +development: + version_tooltip: "Development version" + +home: + strip_header: false + +# structure of website themed with quillt +navbar: + title: ~ + type: default + structure: + left: [intro, examples] + right: [reference, news, github] + components: + home: ~ + examples: + text: Examples + href: articles/articles/examples.html + reference: + text: Reference + href: reference/index.html + github: + icon: fab fa-github fa-lg + href: https://github.com/rstudio/rticles + news: + text: News + menu: + - text: "Changelog" + href: news/index.html + - text: "------------------" + - text: "Blog posts" + # Add blog post where a released version is mentioned. + - text: "No blog post" + # - text: Version 0.2 + # href: + +authors: + footer: + roles: [cre, fnd] + sidebar: + roles: [cre, aut] + +# structure example +reference: + - title: List all available journal templates + contents: + - journals + - title: Journal templates + contents: + - ends_with("article") + + diff --git a/man/figures/logo.png b/man/figures/logo.png new file mode 100644 index 000000000..a5bc9db3e Binary files /dev/null and b/man/figures/logo.png differ diff --git a/pkgdown/favicon/apple-touch-icon-120x120.png b/pkgdown/favicon/apple-touch-icon-120x120.png new file mode 100644 index 000000000..ef06b90ad Binary files /dev/null and b/pkgdown/favicon/apple-touch-icon-120x120.png differ diff --git a/pkgdown/favicon/apple-touch-icon-152x152.png b/pkgdown/favicon/apple-touch-icon-152x152.png new file mode 100644 index 000000000..c40f33fb8 Binary files /dev/null and b/pkgdown/favicon/apple-touch-icon-152x152.png differ diff --git a/pkgdown/favicon/apple-touch-icon-180x180.png b/pkgdown/favicon/apple-touch-icon-180x180.png new file mode 100644 index 000000000..4e3c91dbf Binary files /dev/null and b/pkgdown/favicon/apple-touch-icon-180x180.png differ diff --git a/pkgdown/favicon/apple-touch-icon-60x60.png b/pkgdown/favicon/apple-touch-icon-60x60.png new file mode 100644 index 000000000..a9bc2e279 Binary files /dev/null and b/pkgdown/favicon/apple-touch-icon-60x60.png differ diff --git a/pkgdown/favicon/apple-touch-icon-76x76.png b/pkgdown/favicon/apple-touch-icon-76x76.png new file mode 100644 index 000000000..c5765c071 Binary files /dev/null and b/pkgdown/favicon/apple-touch-icon-76x76.png differ diff --git a/pkgdown/favicon/apple-touch-icon.png b/pkgdown/favicon/apple-touch-icon.png new file mode 100644 index 000000000..cc6f8bc26 Binary files /dev/null and b/pkgdown/favicon/apple-touch-icon.png differ diff --git a/pkgdown/favicon/favicon-16x16.png b/pkgdown/favicon/favicon-16x16.png new file mode 100644 index 000000000..ba964a610 Binary files /dev/null and b/pkgdown/favicon/favicon-16x16.png differ diff --git a/pkgdown/favicon/favicon-32x32.png b/pkgdown/favicon/favicon-32x32.png new file mode 100644 index 000000000..d1dc54a1b Binary files /dev/null and b/pkgdown/favicon/favicon-32x32.png differ diff --git a/pkgdown/favicon/favicon.ico b/pkgdown/favicon/favicon.ico new file mode 100644 index 000000000..8578ed3b6 Binary files /dev/null and b/pkgdown/favicon/favicon.ico differ diff --git a/tests/testit/test-formats.R b/tests/testit/test-formats.R index 27cacd25d..51c7054e7 100644 --- a/tests/testit/test-formats.R +++ b/tests/testit/test-formats.R @@ -14,7 +14,7 @@ test_format <- function(name, output_options = NULL, os_skip = NULL) { # create a draft of the format testdoc <- paste0(name,"_article",".Rmd") rmarkdown::draft( - testdoc, pkg_file("rmarkdown", "templates", name), + testdoc, pkg_file_template(name), create_dir = FALSE, edit = FALSE ) diff --git a/vignettes/.gitignore b/vignettes/.gitignore new file mode 100644 index 000000000..097b24163 --- /dev/null +++ b/vignettes/.gitignore @@ -0,0 +1,2 @@ +*.html +*.R diff --git a/vignettes/articles/.gitignore b/vignettes/articles/.gitignore new file mode 100644 index 000000000..44b9a86d6 --- /dev/null +++ b/vignettes/articles/.gitignore @@ -0,0 +1,3 @@ +resources +cache +examples.yml diff --git a/vignettes/articles/_child_examples.Rmd b/vignettes/articles/_child_examples.Rmd new file mode 100644 index 000000000..1fbdb85d5 --- /dev/null +++ b/vignettes/articles/_child_examples.Rmd @@ -0,0 +1,69 @@ +--- +title: "child of Examples.Rmd" +--- + +```{r, message = TRUE, warning = TRUE, include = FALSE} +# this is to generate the GIF and PDF for the gallery +# This is done on GHA and there is a caching mechanism so that a new rendering +# occurs only when needed + +library(rticles) +library(magick) + +# dir setup +hash_db_dir <- "cache" +if (!dir.exists(hash_db_dir)) dir.create(hash_db_dir) +out_dir <- "resources" +if (!dir.exists(out_dir)) dir.create(out_dir) + +# exclude ctex for now +journals <- setdiff(journals(), "ctex") + +for (journal in journals) { + hash_db_file <- file.path(hash_db_dir, xfun::with_ext(journal, ".rds")) + out_files <- file.path(out_dir, xfun::with_ext(paste0(journal, "_article"), c("gif", "pdf"))) + # clean cache if no more files + if (!all(file.exists(out_files))) unlink(hash_db_file) + # Should we render new resource ? + resource_path <- rticles:::pkg_file_template(journal) + template_files <- list.files(resource_path, recursive = TRUE) + template_files <- setNames( + file.path(resource_path, template_files), + nm = template_files) + new_hash_db <- lapply(template_files, function(x) unname(tools::md5sum(x))) + if (file.exists(hash_db_file)) { + old_hash_db <- readRDS(hash_db_file) + if (identical(old_hash_db, new_hash_db)) { + message("No changes in templates. Skipping ", + journal, " format.") + next + } + } + message("Rendering to PDF...") + out_pdf <- xfun::try_silent(rticles:::render_draft(journal, quiet = TRUE)) + if (inherits(out_pdf, "try-error")) { + warning("Error with rendering format ", journal, + immediate. = TRUE) + next + } + + message("Converting to GIF...") + pdf_content <- image_read_pdf(out_pdf, density = 72) %>% image_resize(geometry = "400x") + out_gif <- image_write_gif( + image = pdf_content, + path = xfun::with_ext(out_pdf, "gif"), + delay = 1) + message("Retrieving built files.") + # specific treatment for rjournal name + if (journal == "rjournal") { + file.rename(out_pdf, out_pdf <- file.path(dirname(out_pdf), "rjournal_article.pdf")) + file.rename(out_gif, out_gif <- file.path(dirname(out_gif), "rjournal_article.gif")) + } + file.copy(out_pdf, out_dir) + file.copy(out_gif, out_dir) + # clean temp dir + unlink(dirname(out_pdf), recursive = TRUE) + # saving the new hash + saveRDS(new_hash_db, hash_db_file) +} +``` diff --git a/vignettes/articles/examples.Rmd b/vignettes/articles/examples.Rmd new file mode 100644 index 000000000..171f8880c --- /dev/null +++ b/vignettes/articles/examples.Rmd @@ -0,0 +1,82 @@ +--- +title: "Example of journal's templates" +resource_files: + - resources +--- + +```{r, setup, include = FALSE} +library(rticles) +``` + + +```{r, child = "_child_examples.Rmd"} +``` + +```{r, include = FALSE} +# We generate the YAML file on the fly to render the gallery + +# list of sites +articles <- lapply(journals(), function(journal) { + name <- yaml::read_yaml(rticles:::pkg_file_template(journal, "template.yaml"))$name + img = file.path("resources", paste0(journal, "_article.gif")) + href = file.path("resources", paste0(journal, "_article.pdf")) + repo_url = "https://github.com/rstudio/rticles/tree/master/inst/rmarkdown/templates/" + if (!file.exists(img) || !file.exists(href)) return(list()) + list( + title = sprintf("%s - %s", journal, name), + fun = sprintf("%s_article", journal), + img = img, + href = href, + source = paste0(repo_url, journal) + ) +}) + +articles <- Filter(length, articles) +``` + +The examples below illustrate all the article's template included into this package. + +```{r, include = FALSE} +src <- lapply(articles, function(article) { + glue::glue_data(article, paste( + "## {{title}}", + "", + "```yaml", + "output: {{fun}}", + "```", + "", + "::: {.two-columns}", + "[![]({{img}})]({{href}})", + "", + "* Format function: `{{paste0(fun, '()')}}`", + "", + "* [Template Sources]({{source}})", + "", + "* [PDF example]({{href}})", + "", + ":::", + "\n", sep = "\n" + ), .open = "{{", .close = "}}") +}) +res <- knitr::knit_child(text = unlist(src), quiet = TRUE) +``` + +`r res` + +```{css, echo = FALSE} +img { + border: unset; + border-style: solid; + border-color: #FEDB00; +} + +.two-columns { + -webkit-columns: 2 300px; + -moz-columns: 2 300px; + columns: 2 300px; + -webkit-column-gap: 2em; + -moz-column-gap: 2em; + column-gap: 2em; +} +``` + diff --git a/vignettes/rticles.Rmd b/vignettes/rticles.Rmd new file mode 100644 index 000000000..ca898176f --- /dev/null +++ b/vignettes/rticles.Rmd @@ -0,0 +1,35 @@ +--- +title: "Get started" +--- + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) +``` + +## Accessing templates + +```{r child="usage.md"} +``` + + +View the list of available journal names with `rticles::journals()`. + +## Figure numbering & cross-references + +You may want to use features of the [**bookdown** package](https://pkgs.rstudio.com/bookdown/) like automatic numbering and cross-referencing of figures and tables in your article. To do this, you'll need to follow [**bookdown** documentation](https://bookdown.org/yihui/bookdown/a-single-document.html), i.e. to edit your YAML to: + ++ Switch to the `bookdown::pdf_book` output format, and + ++ Supply your **rticles** template of choice as the `base_format`. + +```{.yaml} +output: + bookdown::pdf_book: + base_format: rticles::peerj_article +``` + + +Read more about using the **rticles** package here: https://bookdown.org/yihui/rmarkdown/journals.html diff --git a/vignettes/usage.md b/vignettes/usage.md new file mode 100644 index 000000000..b339e11fd --- /dev/null +++ b/vignettes/usage.md @@ -0,0 +1,19 @@ + + +To use **rticles** from RStudio, you can access the templates through `File -> New File -> R Markdown`. This will open the dialog box where you can select from one of the available templates: + +![New R Markdown](https://bookdown.org/yihui/rmarkdown/images/rticles-templates.png) + + +If you are not using RStudio, you'll also need to install [Pandoc](https://pandoc.org) following these [instructions](https://bookdown.org/yihui/rmarkdown-cookbook/install-pandoc.html). Then, use the `rmarkdown::draft()` function to create articles: + +```r +rmarkdown::draft( + "MyJSSArticle.Rmd", template = "jss", package = "rticles" +) +rmarkdown::draft( + "MyRJournalArticle", template = "rjournal", package = "rticles" +) +``` + + This will create a folder containing a Rmd file using the corresponding output format and all the assets required by this format.