Initialise an orderly store. This is a helper function that
automates getting started with using orderly for a new project.
It is not required to use - you can create the orderly structure
yourself (all that is compulsory is the orderly_config.yml
file).
Arguments
- root
The root of the store; this must be an empty directory or the path of a directory to create
- doc
Logical, indicating if documentation should be added to the directories. This also has the (potentially useful) effect of making these directories noticeable by git.
- quiet
Logical, indicating if informational messages should be suppressed.
Details
This function creates a minimal orderly structure, containing:
orderly_config.yml: The orderly configuration. Minimally, this can be empty, but it must exist.src: The path where report sources live. This should be placed under version control, and contain a number of reports, each in their own directory with anorderly.ymldescribing their inputs and outputs (artefacts). Theorderly_new()function can be used to accelerate creation of new reports.draft: A directory where reports will be run usingorderly_run(). This directory should be excluded from version control.orderlywill create it as needed if it does not exist when a report is run.archive: A directory where successfully run reports will be moved to after being committed withorderly_commit(). This directory should be excluded from version control.orderlywill create it as needed if it does not exist when a report is committed.data: A directory where data extracted from the database (if used) will be stored. This directory should be excluded from version control.orderlywill create it as needed if it does not exist when a report is run.
See also
orderly_new() for creating new reports within
a configured orderly repository.
Examples
# Initialise a new orderly repository in an temporary directory:
path <- orderly::orderly_init(tempfile())
#> Now, edit the file 'orderly_config.yml' within '/tmp/RtmpGRuIRx/file4711c7bd38'
# This has created the directory skeleton that you need to get
# started using orderly:
fs::dir_tree(path)
#> /tmp/RtmpGRuIRx/file4711c7bd38
#> ├── README.md
#> ├── archive
#> │ └── README.md
#> ├── data
#> │ └── README.md
#> ├── draft
#> │ └── README.md
#> ├── orderly_config.yml
#> └── src
#> └── README.md
# As instructed, the next thing to do is to edit the
# orderly_config.yml file to match your needs:
readLines(file.path(path, "orderly_config.yml"))
#> [1] "# To use external databases, this file must contain the field"
#> [2] "# 'database', which contains database configurations, each of which"
#> [3] "# must contain a field 'driver' that will be one of RSQLite::SQLite or"
#> [4] "# RPostgres::Postgres (other drivers may work too in future, but not"
#> [5] "# yet)."
#> [6] "#"
#> [7] "# For example, a configuration to use Postgres as the source database"
#> [8] "# might look like:"
#> [9] "#"
#> [10] "# database:"
#> [11] "# source:"
#> [12] "# driver: RPostgres::Postgres"
#> [13] "# args:"
#> [14] "# host: localhost"
#> [15] "# port: 5432"
#> [16] "# user: myuser"
#> [17] "# dbname: databasename"
#> [18] "# password: p4ssw0rd"
#> [19] "#"
#> [20] "# All arguments in the \"args\" block will be passed through during the"
#> [21] "# 'DBI::dbConnect()' call."
#> [22] "#"
#> [23] "# If using SQLite, then the \"dbname\" argument will be interpreted"
#> [24] "# relative to the orderly root if not absolute . Be sure to exclude"
#> [25] "# this path using .gitignore"
#> [26] "#"
#> [27] "# Other options accepted by RSQLite are allowed but are much less"
#> [28] "# commonly useful (as of RSQLite v1.1-2, loadable.extensions,"
#> [29] "# cache_size, synchronous, flags, vfs)"
#> [30] "database: ~"
#> [31] ""
#> [32] "# It is not necessary to configure a destination driver explicitly"
#> [33] "# unless you want to change the default (which is into a SQLite"
#> [34] "# database called \"orderly.sqlite\" at the orderly root. If you do"
#> [35] "# specify it, the options are the same as for \"source\", e.g.:"
#> [36] "#"
#> [37] "# destination:"
#> [38] "# driver: RSQLite::SQLite"
#> [39] "# args:"
#> [40] "# dbname: different.sqlite"
#> [41] ""
#> [42] "# In addition, it may contain a 'fields' section defining custom"
#> [43] "# fields, for example:"
#> [44] "#"
#> [45] "# fields:"
#> [46] "# comment:"
#> [47] "# required: true"
#> [48] "# type: character"
#> [49] "#"
#> [50] "# Each field is named, and has two required entries; 'required'"
#> [51] "# (either false or true) and 'type' (either 'character' or 'numeric')."
#> [52] "#"
#> [53] "# The fields must not clash with built-in field names."
#> [54] "fields: ~"