Create new report, starting from a template. Orderly comes with a set of templates, but projects can bring their own templates; see Details below for how these are configured and discovered by orderly.

orderly_new(name, root = NULL, locate = TRUE, quiet = FALSE, template = NULL)

Arguments

name

Name of the new report (will be a directory name).

root

The path to an orderly root directory, or NULL (the default) to search for one from the current working directory if locate is TRUE.

locate

Logical, indicating if the configuration should be searched for. If TRUE and config is not given, then orderly looks in the working directory and up through its parents until it finds an orderly_config.yml file.

quiet

Logical, indicating if informational messages should be suppressed.

template

The name of a template. If NULL orderly will search for a template (see Details). If given it must be the name of a directory within a directory templates in your project root. The special label "orderly" will use orderly's builtin template.

Value

The path of the new source directory, invisibly

Details

To create a custom template, create a directory templates within your orderly root. Within that directory create directories containing all the files that you would like a report to contain. This must contain a file orderly.yml but may contain further files (for example, you might want a default script and Rmd file).

If template is not given (i.e., is NULL) then we look for a template called default (i.e., stored at template/default), then fall back on the system orderly template.

We first look for a file orderly/template.yml within the orderly root. If that is not found, then a copy from the orderly package is used. This can always be used by using template = "system".

See also

orderly_init() for initialising a new orderly repository.

Examples

path <- orderly::orderly_example("minimal")

# Create a new report with the name "myreport" in this orderly
# repository:
orderly::orderly_new("myreport", root = path)
#> Created report at '/tmp/RtmpP7mCov/file4625b6711e/src/myreport'
#> Edit the file 'orderly.yml' within this directory

# The directory will be initialised with a orderly.yml file
# containing documentation
dir(file.path(path, "src", "myreport"))
#> [1] "orderly.yml"
readLines(file.path(path, "src", "myreport", "orderly.yml"))
#>   [1] "# This is an example orderly configuration file - edit it to suit your"  
#>   [2] "# needs.  The fields \"script\" and \"artefacts\" are the only"          
#>   [3] "# ones required (plus whatever your project lists in the root"           
#>   [4] "# configuration) so they are listed first here.  After that optional"    
#>   [5] "# fields are listed.  The order does not matter so reorder to suit"      
#>   [6] "# yourself."                                                             
#>   [7] "#"                                                                       
#>   [8] "# The \"data\" section will typically contain one or more fields with"   
#>   [9] "# the name corresponding to an R object you want and the value"          
#>  [10] "# corresponding to the SQL query to pull that data from the database."   
#>  [11] "# You can use a filename instead of an inline query.  Run queries to"    
#>  [12] "# multiple lines using the `>-` yaml syntax."                            
#>  [13] "#"                                                                       
#>  [14] "#     data:"                                                             
#>  [15] "#       dat: SELECT field1, field2 FROM table"                           
#>  [16] "#       more: >-"                                                        
#>  [17] "#         SELECT field1, field2"                                         
#>  [18] "#           FROM table1 JOIN table2"                                     
#>  [19] "#             ON table1.id = table2.fk"                                  
#>  [20] "#       another: from_file.sql"                                          
#>  [21] "#"                                                                       
#>  [22] "# If you are writing a report that uses only artefacts from other"       
#>  [23] "# reports, you can omit this field."                                     
#>  [24] ""                                                                        
#>  [25] "# You must have a script that does something with the data.  This"       
#>  [26] "# will be a single string and the filename must exist when orderly is"   
#>  [27] "# run"                                                                   
#>  [28] "script: ~"                                                               
#>  [29] ""                                                                        
#>  [30] "# You must list at least one artefact that your report will generate."   
#>  [31] "# Each artefact consists of one or more files.  The format is to list"   
#>  [32] "# the \"type\" of an artefact (staticgraph, interactivegraph, data,"     
#>  [33] "# report), then below that a description (free text) and then a"         
#>  [34] "# filename as either a single file or an array of files"                 
#>  [35] "#"                                                                       
#>  [36] "#     artefacts:"                                                        
#>  [37] "#       - staticgraph:"                                                  
#>  [38] "#           description: A graph of things"                              
#>  [39] "#           filenames: mygraph.png"                                      
#>  [40] "#       - report:"                                                       
#>  [41] "#           description: A complex report"                               
#>  [42] "#           filenames:"                                                  
#>  [43] "#             - report.html"                                             
#>  [44] "#             - figures/fig1.png"                                        
#>  [45] "#             - figures/fig2.png"                                        
#>  [46] "artefacts: ~"                                                            
#>  [47] ""                                                                        
#>  [48] "# An optional name to describe the report in more detail than its"       
#>  [49] "# directory name (which must be short) but less detail than"             
#>  [50] "# \"description\" (which can be as long as you want).  Must be a string."
#>  [51] "#"                                                                       
#>  [52] "# displayname:"                                                          
#>  [53] ""                                                                        
#>  [54] "# An optional free-text description to decsribe the report in as much"   
#>  [55] "# detail as you want.  Must be a string.  The yaml `>-` or `|` syntax"   
#>  [56] "# might be useful for long descriptions."                                
#>  [57] "#"                                                                       
#>  [58] "# description:"                                                          
#>  [59] ""                                                                        
#>  [60] "# Optional parameters to the report.  These will be substituted into"    
#>  [61] "# the SQL queries.  For example:"                                        
#>  [62] "#"                                                                       
#>  [63] "# parameters:"                                                           
#>  [64] "#   a:"                                                                  
#>  [65] "#     default: 1"                                                        
#>  [66] "#   b: ~"                                                                
#>  [67] "#"                                                                       
#>  [68] "# would declare a parameter called 'a' with a default value of 1, and"   
#>  [69] "# a parameter of b with no default."                                     
#>  [70] "#"                                                                       
#>  [71] "# parameters:"                                                           
#>  [72] ""                                                                        
#>  [73] "# Similar to \"data\" but sets of temporary views before the data are"   
#>  [74] "# extracted.  Can be embedded SQL strings or filenames to actual"        
#>  [75] "# queries.  Use this to simplify the extraction."                        
#>  [76] "#"                                                                       
#>  [77] "# views:"                                                                
#>  [78] ""                                                                        
#>  [79] "# Packages that should be loaded before the script is run.  Use this"    
#>  [80] "# in preference to explicit library() calls in your script because it"   
#>  [81] "# will make it easier to provision containers to run the orderly"        
#>  [82] "# reports."                                                              
#>  [83] "#"                                                                       
#>  [84] "# packages:"                                                             
#>  [85] ""                                                                        
#>  [86] "# Source files, in addition to the script.  Typically these will"        
#>  [87] "# contain function definitions.  These will be sourced after loading"    
#>  [88] "# any packages, and before running your script.  Use this in"            
#>  [89] "# preference to explicit source() calls in your script because"          
#>  [90] "# otherwise you will have to add them to \"resources\" (see below)"      
#>  [91] "#"                                                                       
#>  [92] "# sources:"                                                              
#>  [93] ""                                                                        
#>  [94] "# Resources that the script needs to run; this is an array of strings"   
#>  [95] "# representing filenames *relative to, and below, this directory*."      
#>  [96] "# These will be copied into place when the script is run, and again"     
#>  [97] "# when commiting the report.  If you require a file and do not list it"  
#>  [98] "# here, your script will fail!  (That's a good thing because we find"    
#>  [99] "# out what your script actually needed immediately).  You do not need"   
#> [100] "# to list files already listed in \"sources\" here, or any .sql files"   
#> [101] "# referenced in \"views\" or \"data\""                                   
#> [102] "#"                                                                       
#> [103] "# resources:"                                                            
#> [104] ""                                                                        
#> [105] "# Optional name of a variable to make the SQL connection available to"   
#> [106] "# the script.  Use this with care and avoid using any queries that"      
#> [107] "# modify the database (i.e., use DBI::dbGetQuery with \"SELECT\" queries"
#> [108] "# *only*.  Must be a string."                                            
#> [109] "#"                                                                       
#> [110] "# connection:"                                                           
#> [111] ""                                                                        
#> [112] "# Indicate which reports your report depends on.  You can use this to"   
#> [113] "# pull in artefacts from previous reports.  You can depend in multiple"  
#> [114] "# reports.  The format looks like this:"                                 
#> [115] "#"                                                                       
#> [116] "#     depends:"                                                          
#> [117] "#       other_report_name:"                                              
#> [118] "#         id: (identifier, possibly \"latest\")"                         
#> [119] "#         use: (mapping of filenames in the format dest: from)"          
#> [120] ""                                                                        
#> [121] "# For example, to depend on the latest version of report"                
#> [122] "# 'other-report', pulling in 'data.csv' as 'other-data.csv' you might"   
#> [123] "# use:"                                                                  
#> [124] "#"                                                                       
#> [125] "#     depends:"                                                          
#> [126] "#       other-report:"                                                   
#> [127] "#         id: latest"                                                    
#> [128] "#         use:"                                                          
#> [129] "#           other-data.csv: data.csv"                                    
#> [130] "#"                                                                       
#> [131] "# depends:"