workflowr does this automatically, using git2R (or git2r, not sure).

Option 1

• Automatically name initial report <project_name>V1 in _bookdown.yml$book_filename.
• Allow an automatic versioning check, which:
  • Bumps version up.
  • Only runs if there are no files in the Git working directory, and records the last Git commit.
  • Copies outputted document to .archive.
  • Requests an update to NEWS.md
  • Possibly auto-generates a detailed changes file, which shows changes to "important" objects (such as "data/" files.

• Purpose is to set directories for which there are no standard R directories, really, and about which there might be disagreement or good reason to choose between different options
  • Example of a good reason
    • Keeping large raw data and output in /scratch but code in /home

Possible features

• #41
• #40
• #42

Quarto

• Quarto essentially provides a more feature-rich, user-friendly interface to RMarkdown-style Markdown and extends it to Python, Julia and Observable.

What does Quarto not do that I am proposing (out the box)

• Allow user-specific project directories (such as dir_cache and dir_archive
• Work directly with bookdown
• Implement automated but flexible versioning
• Facilitate easier raw data management
• Implement Docker containers easily
• Create nice in-folder log messages
• Create set-up document with specific things to change
• Wrap into an R package
• Wrap useful Git workflows
• Set

Aims to generate a project directory structure.

• Source
• Pros
  • Generates project directory structure
• Cons
  • Doesn't seem to allow user-specific project directory structures

• Zenodo seems to have no size limits (question "What are the size limits in Zenodo?)
  • Has an R package for this: https://github.com/karthik/zenodo

Sets up an R project

• Source
• Pros
  • Sets up project structure
  • Aims to review project health report
• Cons
  • Last changed a couple years ago
    • Doesn't seem to be taking on templates then
  • Does not seem to use bookdown
• Overall
  • Seems to aim at a similar thing to what we want to do, but seems to no longer be maintained.

Generates a website that is reproducible in the sense that it is time-stamped and versioned.

• Source
• Pros
  • Explicit versioning upon publication
    • Use Git to do that.
  • Runs analyses in isolated R sessions
  • Records session information from each analysis
  • Sets seeds
  • Able to set Git up for you using workflowr commands
• Cons
  • Only outputs HTML format
  • Fixed R folder directory
  • Does not build to a package - not ideal.
  • Does not use renv automatically
  • Have to learn to use bookdown for non-HTML multi-page documents
• Overall
  • No real reason not to use a project structure that also builds into a package
    • Not everything is a report

• Pros
  • Automatically has sections you would
    • Abstract
    • Appendix
    • Acknowledgments
• Cons
  • No automatic versioning

Can show how long issues took to be resolved using viz_gantt.

Seems like workflowr package.
GitHub page for sandpaper.

Oh, this is actually for creating lesson websites.
Seems useful, though!

• Examples
  • Build on your own dev branch
  • Upon (successful) major rebuild:
    • Squash commits since last major rebuild/first commit
    • Prompt the commit message
    • Push latest commit
    • Submit pull request/merge into main branch

• Source: https://github.com/NikKrieger/projects
• Pros
  • Can allow archiving of projects
  • Has a central directory of author information
  • Prints to the console useful snippets
• Cons
  • A central database just seems cumbersome and not portable
    • A person may have different projects in different places
  • Uses rds files, that do not translate across users.
  • Seems like a lot of extra stuff to remember that doesn't really help that much.
  • Does not use bookdown.
  • Seems like a real commitment to their format.
  • Archiving not linked to Git commits.
• Overall
  • Seems like quite a commitment for author metadata and project folders
    • Author metadata is something you'll have to manually enter time and again anyway.

• bookdown-centric
  • Allows cross-linking, multi-page output, multiple formats, established, R-specific
  • Most natural progression from RMarkdown
    • Very easy to use - one extra file to understand! (_bookdown.yml)
• Follow R package structure where applicable
  • R/, data/
• Allow user-specifiable and re-usable structures for non-R package folders
  • Where Rmd's go
  • Intermediate results
  • Final output
  • Author details (use usethis)
• Clean, natural versioning
  • Automatically increment report version number and tag with last Git commit when the report is built under the following conditions:
    • User requests it
    • Working directory is empty
    • Possibly:
      • data/ folder is empty
• Save key outputs to output/sharing/publish folder:
  • Processed data
    • In R and non-R format (as applicable)
  • Link to raw data
    • Raw data should already be in another folder
  • Tarball of package (if it is a package)
• Allow publishing to website automatically
  • Create orphaned gh-pages branch that contains just the last report
• Automatically set up key tools:
  • git
  • renv
• Log raw data used
  • Keep an md file within each
  • Keep hash table on each file within raw data
• Appendices summarising useful information
  • utils::sessionInfo() from when book was last built
  • Put together md's from raw data folder(s)
  • Possibly summarise raw data (# of files/directory).
  • Project folder structure
  • Summarise changes in Git between versions
    • List all commits
    • List all files that have changed
• Zero (or near-zero) dependencies for install
  • Dependencies are unnecessary when you're just loading data or trying to access a link to view a report.
• Position on Docker
  • In R, your main dependencies are already
  • Can build on cluster if you want a different computer.
  • Can just wipe out the cache folder (possibly the raw data directory) and recompute the renv/ library if you're worried.
    • Can clone to a different location and set up again there.
• Templates
  • Examples
    • README for data package projects
    • README that specifies project structure automatically
      • As well as links to raw data
    • Analysis Rmd
      • Gives sections and Markdown comments saying what to put in each section
        • Examples of headings:
          • Aims, Data (sample size), Methods, Biological information, Study design
• Possible extras:
  • Only rerun report if raw data, R files, Rmd's or key package versions in lock file have changed.
  • Add functions for package even if it's just a report:
    • Link to download raw data
    • Link to view report online
    • Link to repo

Reportr is taken (as a CRAN repo, too), but projr is not. Could be good, as it’s short and doesn’t specify how the reporting happens (which leaves pkgdown and others as alternatives to book down for reporting).

A major draw of workflowr. All we would have to do, though, is write a shell script to create the orphaned gh-pages branch and push it.

• Could create a Google shared drive from command line

• I think the best way would be to:
  • Allow setting the PROJR_YML_DEFAULT_PATH variable, which is automatically used whenever path isn't specified if it is set.
  • Suggest to people that they save the paths as environment variables, and then use projr::projr_init(path = NULL, path_env = <env_var_name>).
• BETTER suggestion:
  • Allow people to set PROJR_YML_PATH_<settings_id>, and then when they run projr::projr_init, they get the following options for _projr.yml:
  • 1: projr` package default
  • 2: <settings_id_1>
  • 3: <settings_id_2>
  • ...

projects package suggested this.

• What do they print?
  • R Markdown YAML headers

Definitely necessary

Likely necessary

• book_filename:

Useful

• rmd_files
• output_dir
  • Set this equal to <something>/<book_filename>

This is the file set up where the cache is etc.

pagedown paginates HTML output for printing.

Possible features of raw data

• Make it a GitHub repo
• Allow uploading only the last commit as a branch to GitHub
• Check that every item is documented
• Create structure for automated commit message
• Ensure that old versions are retained when uploading to Google Drive (or prompt a reminder to do, such as creating a GitHub issue)
• Detect if raw data have changed since last log message
• Write down the details of when the raw data were last modified and what they were (well, whatever was in each folder)

• For example, we can have a standard structure for where the project files go.
• But then somebody could submit a different structure, and then use that.

At present, I've just used Output<package_name>. But perhaps Publish<package_name> is better? Or Share<package_name>?

https://github.com/rocker-org/binder

Sources:

• r-project-workflows

Possible features

• #31
• [ ]#282
• [ ]

Essential features

• Differentiate between major and minor builds
• Allow manual version bumping
• #143
• Record package state if build was successful
• Output version bump message
• #142
• #135

Non-essential features

• Consider enforcing that GitHub working directory is clean before build
• Consider automatic building of Git commits
• Consider notifying team members if successful

Probably a good idea to use the bookdown defaults, but replace the references to bookdown with references to the project or its GitHub repository:

bookdown::gitbook:
  css: style.css
  config:
    toc:
      before: |
        <li><a href="./">A Minimal Book Example</a></li>
      after: |
        <li><a href="https://github.com/rstudio/bookdown" target="blank">Published with bookdown</a></li>
    edit: https://github.com/USERNAME/REPO/edit/BRANCH/%s
    download: ["pdf", "epub"]
bookdown::pdf_book:
  includes:
    in_header: preamble.tex
  latex_engine: xelatex
  citation_package: natbib
  keep_tex: yes
bookdown::epub_book: default

For example, the above would become

bookdown::gitbook:
  css: style.css
  config:
    toc:
      before: |
        <li><a href="./">DataTidy22BCGCorrPilot</a></li>
      after: |
        <li><a href="https://github.com/SATVILab/DataTidy22BCGCorrPilot" target="blank">DataTidy22BCGCorrPilot</a></li>
    edit: https://github.com/SATVILab/DataTidy22BCGCorrPilot/edit/BRANCH/%s
    download: ["pdf", "epub"]
bookdown::pdf_book:
  includes:
    in_header: preamble.tex
  latex_engine: xelatex
  citation_package: natbib
  keep_tex: yes
bookdown::epub_book: default

Use case(s)

• Create presentation(s) in addition to main report
• Create short versions of report (e.g. figures only)

Sets up a re-usable project template

• Source
• Pros
  • Re-usable, flexible templates that don't require synchronising with an online version
• Cons
  • Doesn't do anything, really, besides the file structure.
    • Seems like we could just implement this kind of idea ourselves?
      • This is basically what the _project.yml file is.

Comprehensive set-up for project.

• Source

prodigenr does this, as did Greg in the TuberculomicsCompendium README.

Can use checker.

templates, for example, does this.

Minimum required files

• _bookdown.yml
• index.Rmd
• Possibly _output.yml

Options

• NEWS
• README
• index.Rmd
  • Which options within there?

It's not really that hidden a folder as .cache would suggest. It disappears on Linux, which is annoying.

It's still a better name than tmp, though (as used by analysis_framework), as tmp kind of sounds like something ephemeral, whereas the cached results are sometimes PRECIOUS if they take long to run.

• May be useful for developing manuscripts
  • rticles gives great formats, may need to add wrappers around it, though.
  • rmdTemplates gives templates for things like Beamer slides
    • Less specific to a particular journal than rticles, more general purpose

• renv does this - can choose whether the version-control service monitors things like /cellar or not.