Merge pull request #137 from mrc-ide/mrc-5272

mrc-5272: Add documentation about how to share a packets with shared file system

vignettes/collaboration.Rmd

@@ -16,6 +16,8 @@ path_git <- file.path(path, "git")
 path_alice <- file.path(path, "alice")
 path_bob <- file.path(path, "bob")
 path_server <- file.path(path, "server")
+path_sharepoint_alice <- file.path(path, "sharepoint")
+path_sharepoint_bob <- path_sharepoint_alice
 
 src <- system.file("example", package = "orderly2", mustWork = TRUE)
 fs::dir_copy(src, path_git)
@@ -94,10 +96,10 @@ Packets that are distributed by locations might have been created by `orderly2`,
 
 `orderly2` supports two types of locations by default:
 
-* `path`: these are any `orderly2` working copy that you can find on your filesystem. Note that this could be a copy that other people can see (for example on a network share, or on a cloud-synced file system such as Dropbox or OneDrive)
+* `path`: these are any `orderly2` working copy that you can find on your filesystem. Note that this could be a copy that other people can see (for example on a network share, or on a cloud-synced file system such as Dropbox or OneDrive) see [Sharing packets with collaborators using a shared file system] for more details
 * `http`: these require running an HTTP API, either via [`outpack_server`](https://github.com/mrc-ide/outpack_server) or [`packit`](https://github.com/mrc-ide/packit)
 
-The location system is somewhat extensible, but the details of this are subject to change.  There is [`outpack.sharepoint`](https://github.com/mrc-ide/outpack.sharepoint) for using SharePoint, and we may write other backends later.
+The location system is somewhat extensible, but the details of this are subject to change.
 
 All the documentation below will behave the same regardless of where the location is stored and the mechanism of transport, so we can focus instead on workflows.
 
@@ -242,3 +244,47 @@ If Alice and Bob were starting on a new machine they would:
 Without running `orderly2::orderly_init()`, they will get an error prompting them to initialise the repo.
 
 There is no requirement for different repositories to share configuration options passed to `orderly2::orderly_init()`; so you can enable or disable the file store or have different sets of locations enabled, depending on your workflows. This means that there is, in practice, only an association _by convention_ between a set of related `orderly2` locations and their source tree and you can have an `orderly2` repository that points at locations that refer to different source trees!
+
+# Sharing packets with collaborators using a shared file system
+
+One of the simplest ways to share packets with a collaborator is through a shared file system, for example on a network share, or on a cloud-synced file system such as Dropbox or OneDrive. You can do this as follows.
+
+1. Create a a new folder for your orderly remote in the shared file system. Here Alice has synced to `path_sharepoint_alice`.
+1. Initialise an orderly location on the shared file system
+    ```{r as="alice"}
+orderly2::orderly_init(
+  root = path_sharepoint_alice, 
+  path_archive = NULL, 
+  use_file_store = TRUE, 
+  require_complete_tree = TRUE
+)
+    ```
+    
+   Create an orderly store with a file store and a complete tree. See `orderly2::orderly_init()` for more details.
+1. Add this as a location
+    ```{r, as="alice", inwd = path_alice}
+orderly2::orderly_location_add(
+  "sharepoint", "path", list(path = path_sharepoint_alice))
+    ```
+    
+1. Push any packets you want to share
+    ```{r, as="alice", inwd = path_alice}
+orderly2::orderly_location_push(id, "sharepoint")
+    ```
+
+Then these will be available for your collaborator to pull. Note that the data is pushed into a file store in the `.outpack` directory. `.dot` files are considered hidden by your operating system, so if you have "show hidden files" off in your file browser you will not see the pushed packet. But your collaborator can now pull the shared file. To do so, they will have to:
+
+1. Sync the same drive to a location on their machine. Here Bob has synced to `path_sharepoint_bob`
+1. Add the location
+    ```{r, as="bob", inwd = path_bob}
+orderly2::orderly_location_add(
+  "alices_orderly", "path", list(path = path_sharepoint_bob))
+    ```
+    
+1. Pull the metadata and use the packets as desired
+    ```{r, as="bob", inwd = path_bob}
+orderly2::orderly_location_pull_metadata(
+  "alices_orderly"
+)
+    ```
+