upstream merge template repository

CHANGELOG_SDK.md

@@ -1,4 +1,7 @@
 # Changelog SDK
+## XXX XXX
+- update of `README.md` including new sections
+- update of `developer_README.md`
 
 ## 2024-03 `v3.2.0`
 

Dockerfile

@@ -2,7 +2,7 @@
 # MoveApps R-SHINY SDK
 ########################################################################################################################
 
-FROM rocker/geospatial:4.3.2
+FROM rocker/geospatial:4.4.2
 
 LABEL maintainer = "couchbits GmbH <[email protected]>"
 

developer_README.md

@@ -1,73 +1,42 @@
 # MoveApps R-SHINY Software Development Kit (SDK)
 
-#### ***NOTE*: this SDK only supports code written for input data of class `move2` and not `moveStack`, as all input data of class `moveStack` will be converted to class `move2`. For all other input/output types, this SDK works as usual. Please contact us under [email protected] if you have any questions.**
+***NOTE*: this SDK supports code written for input data of class `move2` and not `moveStack`, as all input data of class `moveStack` will be converted to class `move2`. For all other input/output types, this SDK works as usual. Please contact us under [email protected] if you have any questions.**
 
 This documentation provides a short introduction to the [MoveApps](https://www.moveapps.org) **R-SHINY SDK**.
 
-As a first step, and before your read this, you should have forked this GitHub template to your personal space and named the repository as your App will be named in MoveApps.
-
-A general overview provides the [MoveApps user manual](https://docs.moveapps.org/#/create_app)
-
-# Overview
-
-This template is designed according to a file structure that is necessary for your App to run in your local development environment similar to the way it will run in the MoveApps environment later. Please contain the structure and only change/add files as necessary for your App's functionality. See below which files can be changed and which should remain as is for simulation of the behaviour on MoveApps on your local system. A stepwise explanation below indicates the function and some background of each file and folder.
-
-## File structure
-
-(truncated)
-
-```
-.
-├── Dockerfile
-├── README.md
-├── Template_R_Shiny_App.Rproj
-├── ShinyModule.R
-├── appspec.json
-├── data
-│   ├── auxiliary
-│   ├── output
-│   └── raw
-│       ├── input1.rds
-│       ├── input2.rds
-│       ├── input3.rds
-│       └── input4.rds
-├── renv.lock
-├── sdk.R
-├── src
-│   ├── common
-│   │   ├── logger.R
-│   ├── io
-│   │   ├── app_files.R
-│   │   ├── io_handler.R
-│   │   ├── rds.R
-│   │   └── shiny_bookmark_handler.R
-│   └── moveapps.R
-└── start-process.sh
-
-
-```
-
-1. `./ShinyModule.R`: This is the entrypoint for your App logic. MoveApps will call this module during a workflow execution which includes your App. **The file must be named `ShinyModule.R`, do not alter it!**
-1. `./appspec.json`: This file defines the settings and metadata of your App, for details refer to the [MoveApps User Manual](https://docs.moveapps.org/#/appspec)
-1. `./renv.lock`: Definition of the dependencies of your App. We use `renv` as library manager. Optional.
+As a first step, and before your read this, you should have used this GitHub template to create a copy of it in your personal space and named the repository as your App will be named in MoveApps.
+
+**The [MoveApps User Manual](https://docs.moveapps.org/#/create_app) provides a step-by-step explanation of how to create an App.** Please carefully follow these steps when creating a MoveApps App.
+
+
+## Files in the SDK/template
+
+This template is designed according to a file structure that is necessary for your App to run in your local development environment similar to the way it will run in the MoveApps environment later. Please contain the structure and only change/add files as necessary for your App's functionality. Take a look at the [overview in the User Manual](https://docs.moveapps.org/#/create_app) to see which files can be changed and which should remain as is for simulation of the behaviour on MoveApps on your local system.
+
+Here you find an overview of the files and their function in the SDK:
+
+1. `./ShinyModule.R`: must be modified by the developer. This is the entrypoint for your App logic. MoveApps will call this function during a Workflow execution which includes your App. The file must be named `ShinyModule.R`, do not alter it. See [Step 3](https://docs.moveapps.org/#/create_app#step-3-develop-the-app-code-locally-within-the-template) in the User Manual.
+1. `./appspec.json`: must be modified by the developer. This file defines the settings and metadata of your App. See [Step 5](https://docs.moveapps.org/#/create_app#step-5-write-app-specifications) in the User Manual.
+1. `1. `./README.md`: must be modified by the developer. Provided template for the documentation of the App (see [Step 6](https://docs.moveapps.org/#/create_app#step-6-write-a-documentation-file) in the User Manual).
+1. `./renv.lock`: Definition of the dependencies of your App. We use `renv` as library manager. Optional, see below.
 1. `./data/**`: Resources of the SDK
-   1. `auxiliary/**`: Simulates the usage of [*auxiliary App files*](https://docs.moveapps.org/#/auxiliary). You can put files into this folder to simulate an App run with provided/user-uploaded files. 
-   1. `output/**`: If your App produces [*artefacts*](https://docs.moveapps.org/#/copilot-r-sdk?id=artefacts) they will be stored here.
+1. `./sdk.R`: use for App testing. The main entrypoint of the SDK. Use it to execute your App in your compiler (e.g. RStudio).
+1. `/.env`: adjust for App testing. Defining the SDK Runtime environment, see below. Make sure to check _Show Hidden Files_ in the settings menu of the _Files_ tab in RStudio.
+1. `./data/**`: use for App testing. Resources of the SDK
+   1. `auxiliary/**`: Simulates the usage of [*auxiliary files*](https://docs.moveapps.org/#/auxiliary). You can put files into this folder to simulate an App run with provided/user-uploaded files. 
+   1. `output/**`: The output data (`output.rds`) that will be passed on to the next App in a Workflow and other output files (artifacts) that your App may produce will be stored here. See [*producing artifacts*](https://docs.moveapps.org/#/copilot-shiny-sdk?id=producing-artefacts) for more information.
    1. `raw/**`: Collection of sample App input data. You can use these samples to simulate an App run with real input.
-1. `./sdk/**`: The (internal) MoveApps R SDK logic.
-1. `./sdk.R`: The main entry point of the SDK. Use it to execute your App in your IDE.
+1. all remaining files are used to emulate MoveApps when testing the App locally, to setup the automatic sync of your repository with the template, or to provide information related to the template. **These files are not to be modified**. Modifying them will prevent you from testing your App appropriately. 
 
-## SDK Runtime environment
+## SDK runtime environment
 
-Critical parts of the SDK can be adjusted by `environment variables`. 
-Keep in mind that these variables are only changeable during App development and not during an App run on MoveApps.
-They are predefined with sensible defaults - they should work for you as they are.
+Critical parts of the SDK can be adjusted by `environment variables`. Keep in mind that these variables are only changeable during App development and not during an App run on MoveApps. They are predefined with sensible defaults - they should work for you as they are. While testing your App you will want to modify the `SOURCE_FILE` variable to either call the different example data sets provided in the template or other data sets that you want to use to test your App.
 
 - `SOURCE_FILE`: path to an input file for your App during development
 - `OUTPUT_FILE`: path to the output file of your App
+- `ERROR_FILE`: path to a file collecting error messages
 - `APP_ARTIFACTS_DIR`: base directory for writing App artifacts
-- `USER_APP_FILE_HOME_DIR`: home aka base directory of your local user App files (*auxiliary*)
-- ~~`LOCAL_APP_FILES_DIR`~~: Deprecated! base directory of your local App files (*auxiliary*)
+- `USER_APP_FILE_HOME_DIR`: home aka base directory of your local user/auxiliary App files
 - `CLEAR_OUTPUT`: clears all output of the previously app run at each start of the SDK aka the next app start
 
 You can adjust these environment variables by adjusting the file `./.env`.
@@ -78,51 +47,29 @@ The file `./.env` is **hidden** by default in `RStudio`! You can show it by
 1. `More` Button in the Files-Toolbar
 1. Activate _Show Hidden Files_
 
+
 ## MoveApps App Bundle
 
 Which files will be bundled into the final App running on MoveApps?
 
 - the file `./ShinyModule.R
-- all directories defined in your `appspec.json` at `providedAppFiles` 
-
-Nothing else.
-
-Note that many App features will be set and updated with information from the `appspec.json` in each new App version. Thus, even if not bundled into the App, this file is required and must be up to date.
-
+- all directories defined in your `appspec.json` at `providedAppFiles`
 
-## App development
+- the file `./appspec.json` will be used to build and create the metadata of your App
+- the file `./README.md` will be reference to for the documentation of your App
 
-1. Execute `Rscript sdk.R` (on a terminal) or run/source `sdk.R` in _RStudio_ (_Run App_)
-1. Ensure the sdk executes the vanilla template App code. Everything is set up correctly if no error occurs and you can open the Shiny App in your local Web-Browser.
-1. Begin with your App development in `./ShinyModule.R`
-
-## Examples
-
-### Request App configuration from your users
-
-tbd (Shiny Bookmark instructions)
-
-### Produce an App artefact
-
-tbd (should be supported by SDK - must be tested by sample app implementation. Provide code snippets)
-
-## Include files to your App
-
-[Details and examples about _auxiliary files_](https://docs.moveapps.org/#/auxiliary).
-
-This template also implements in `./ShinyModule.R` a showcase about this topics.
+Nothing else.
 
----
 
 ## R packages management / renv (optional)
 
 The template is prepared to use [`renv` as a dependency manager](https://rstudio.github.io/renv/articles/renv.html) - but is disabled by default (_opt-in_).
 You can [activate `renv` with `renv::activate()`](https://rstudio.github.io/renv/articles/renv.html#uninstalling-renv) and then use it in the [usual `renv` workflow](https://rstudio.github.io/renv/articles/renv.html#workflow).
 
+
 ### Docker support (optional)
 
-- at the end your app will be executed on MoveApps in a Docker container.
-- if you like you can test your app in the almost final environment by running your app locally in a docker container:
+Your app will be executed on MoveApps in a Docker container. Specially for debugging errors that are not straight forward, it can be very useful to execute your App in a docker container. These more complex errors are often due to system libraries that need to be installed in MoveApps to run the App. The easiest way to find out which ones they are is to run the App locally in a docker container:
 
 1. enable `renv` (see above)
 1. set a working title for your app by `export MY_MOVEAPPS_APP=hello-world` (in your terminal)
@@ -131,6 +78,7 @@ You can [activate `renv` with `renv::activate()`](https://rstudio.github.io/renv
 1. you will get a `bash` terminal of the running container. There you can get a R console by `R` or simply start your app by invoking `/home/moveapps/co-pilot-r/start-process.sh` (in the `bash` of the running container)
 1. after starting the process open your app UI by navigating to `http://127.0.0.1:3838/` (in your local web browser)
 
+
 ## Synchronisation of your fork with this template
 
-This template includes a _GitHub action_ to keep your fork synchronized with the original template (aka the MoveApps R SDK). The synchronization action creates a _GitHub pull request_ in your fork from time to time in case the original template has changed.
+This template includes a _GitHub action_ to keep your copy synchronized with the original template. Take a look at the [documentation](https://docs.moveapps.org/#/manage_Rapp_github?id=keep-your-repositories-up-to-date-sync-with-templates) and make sure to keep your repository up-to-date.