Merge pull request #6 from Displacement-Tracking-Matrix/dev

Changes in configurations and dev version 0.1.9000

Author: bangtranl

.github/workflows/pkgdown.yaml

@@ -21,6 +21,7 @@ jobs:
       group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      DTMAPIR_KEY: ${{ secrets.DTMAPIR_KEY }}
     permissions:
       contents: write
     steps:

.gitignore

@@ -5,4 +5,4 @@ inst/doc
 .Renviron
 .Rhistory
 /.quarto/
-docs
+docs

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: dtmapi
 Title: Fetching Data from the 'Displacement Tracking Matrix'
-Version: 0.1.0
+Version: 0.1.0.9000
 Authors@R: c( 
   person("Luong Bang", "Tran", email = "lutran@iom.int", role = c("aut")),
   person("Assad", "Asil Companioni", email = "aasil@iom.int", role = c("aut", "cre")),

NEWS.md

@@ -1,3 +1,14 @@
+# dtmapi (development version)
+* Stylistic and stylistic-adjacent corrections to documentation.
+
+* More elaborate explanation on how to set the subscription key, including
+options for non-interactive environments and explicitly introducing the concept
+of secrets management.
+
+* Substantial corrections to documentation, including clarification of the environment variable being used (it is `DTM_SUBSCRIPTION_KEY`, not `DTM_API_KEY`).
+
+* Apparently inconsequential change in API endpoint URL used by `get_all_operations()`: from "https://dtmapi.iom.int/v3/displacement/operation-List" to https://dtmapi.iom.int/v3/displacement/operation-list", but worth implementing to be safe and exact.
+
 # dtmapi 0.1.0
 
 * Version 3 of the DTM API requires the use of a valid subscription key in order
@@ -18,4 +29,4 @@ the API.
 the `dtmapi` package, but it may technically be used by users to conveniently 
 return the currently available subscription key. HOWEVER, beware that the string
 it returns is plain text and is more easily exposed, e.g. exposed to anyone 
-visually observing your machine.
+visually observing your machine.

R/get_all_operations.R

@@ -13,7 +13,7 @@
 get_all_operations <- function() {
 
   tryCatch({
-    api_url <- "https://dtmapi.iom.int/v3/displacement/operation-List"
+    api_url <- "https://dtmapi.iom.int/v3/displacement/operation-list"
 
     response <- 
       request(api_url) |>

R/get_subscription_key.R

@@ -2,8 +2,8 @@
 #'
 #' The DTM API subscription key is returned, provided that it is available in
 #' the R session as an environment variable. Users will usually need to set 
-#' the DTM_SUBSCRIPTION_KEY environment variable through a .Renviron file or
-#' by calling `set_subscription_key()`.
+#' the DTM_SUBSCRIPTION_KEY environment variable through a .Renviron file (or
+#' other means) or by calling `set_subscription_key()`.
 #' 
 #' On the other hand, if the TESTTHAT environment variable is true, indicating
 #' that unit tests are being run by the package maintainers, then the

R/set_subscription_key.R

@@ -1,11 +1,12 @@
 #' Set the user's API subscription key in order to make the API calls.
 #'
-#' The API will be stored as an environmental variable named "DTM_API_KEY".
+#' The API subscription key will be stored as an environment variable named 
+#' "DTM_SUBSCRIPTION_KEY".
 #' @param key 
 #' Either NULL or a string representing the key. NULL is preferable: using it 
 #' will prompt the user to type the subscription key in a graphical user 
 #' interface that masks it.
-#' @return Nothing. Creates / overwrites an environmental variable as a side effect.
+#' @return Nothing. Creates / overwrites an environment variable as a side effect.
 #' @export
 #' @examples
 #' \dontrun{

README.Rmd

@@ -52,15 +52,23 @@ the [DTM API Portal](https://dtm-apim-portal.iom.int/signin) and follow the
 instructions there. 
 
 The subscription key is secret and should not be exposed. Once it is obtained,
-the subscription key should be set for your current R session, assuming that the
-`dtmapi` package is installed. To do this, use run the following in R:
+the subscription key should be set for your current R session, assuming that the `dtmapi` package is installed. To do this, the environment variable `DTM_SUBSCRIPTION_KEY` needs to be defined. This can be done either interactively or non-interactively. 
+
+The interactive option is to call `set_subscription_key()`, like so:
 
 ```{r set_subscription_key_demo, eval = FALSE}
 dtmapi::set_subscription_key()
 ```
 
-At this point, the user will be prompted to input the key (hidden) into a pop-up
-field.
+At this point, the user will be prompted to input the key (hidden) into a pop-up field.
+
+Some environments are non-interactive, and so running the above will likely result in an error. In such a case, the subscription key may be set non-interactively, by specifying the `key` parameter, like so:
+```{r, eval = FALSE}
+# Specifying `key` is required for non-interactive use.
+dtmapi::set_subscription_key(key = "mysubscriptionkey")
+```
+
+However, this option is discouraged and should be avoided as much as possible, because it blatantly exposes the subscription key. The best option would be to engage in good secrets management practices, such as by using a .Renviron file (if applicable). Basic secrets management, and the issue of setting the subscription key in general, is elaborated on in more detail in `vignette("user_guide")`.
 
 ## Usage
 When the subscription key is set, data on internal displacement may be retrieved through any of the following functions:
@@ -74,8 +82,7 @@ These all retrieve data from the DTM API and return said data in
 the form of data frames.
 
 Certain parameters have to be specified to any of these, the most important of which are either the `CountryName` or the `OperationName`. For information on the other parameters 
-and indeed all functions in `dtmapi`, 
-[see the documentation here.](https://displacement-tracking-matrix.github.io/dtmapi-R/reference/index.html)
+and indeed all functions in `dtmapi`,  [see the documentation here.](https://displacement-tracking-matrix.github.io/dtmapi-R/reference/index.html)
 
 As a representative example of the earlier mentioned functions, see the following use of `get_idp_admin_1_data()`:
 
@@ -117,13 +124,15 @@ head(operations_df)
 
 ## User Guide
 The information given here is further elaborated on in the user guide to
-getting started with `dtmapi`, which is available through the panel at 
-the top of this page.
+getting started with `dtmapi`, which is 
+accessible through `vignette("user_guide")`.
 
 ## Source Code
-The source code for `dtmapi` is available on [GitHub](https://github.com/Displacement-tracking-Matrix/dtmapi-R).
+The source code for `dtmapi` is available on 
+[GitHub](https://github.com/Displacement-tracking-Matrix/dtmapi-R).
 
 Feel free to explore the repository, contribute, or raise any issues you may encounter.
 
 ## Contact
-For any questions or feedback, please reach out to us at [dtmdataconsolidation@iom.int](mailto:dtmdataconsolidation@iom.int).
+For any questions or feedback, please reach out to us at 
+[dtmdataconsolidation@iom.int](mailto:dtmdataconsolidation@iom.int).

README.md

@@ -53,8 +53,11 @@ the instructions there.
 
 The subscription key is secret and should not be exposed. Once it is
 obtained, the subscription key should be set for your current R session,
-assuming that the `dtmapi` package is installed. To do this, use run the
-following in R:
+assuming that the `dtmapi` package is installed. To do this, the
+environment variable `DTM_SUBSCRIPTION_KEY` needs to be defined. This
+can be done either interactively or non-interactively.
+
+The interactive option is to call `set_subscription_key()`, like so:
 
 ``` r
 dtmapi::set_subscription_key()
@@ -63,6 +66,22 @@ dtmapi::set_subscription_key()
 At this point, the user will be prompted to input the key (hidden) into
 a pop-up field.
 
+Some environments are non-interactive, and so running the above will
+likely result in an error. In such a case, the subscription key may be
+set non-interactively, by specifying the `key` parameter, like so:
+
+``` r
+# Specifying `key` is required for non-interactive use.
+dtmapi::set_subscription_key(key = "mysubscriptionkey")
+```
+
+However, this option is discouraged and should be avoided as much as
+possible, because it blatantly exposes the subscription key. The best
+option would be to engage in good secrets management practices, such as
+by using a .Renviron file (if applicable). Basic secrets management, and
+the issue of setting the subscription key in general, is elaborated on
+in more detail in `vignette("user_guide")`.
+
 ## Usage
 
 When the subscription key is set, data on internal displacement may be
@@ -80,8 +99,6 @@ important of which are either the `CountryName` or the `OperationName`.
 For information on the other parameters and indeed all functions in
 `dtmapi`, [see the documentation
 here.](https://displacement-tracking-matrix.github.io/dtmapi-R/reference/index.html)
-`dtmapi`, [see the documentation
-here.](https://displacement-tracking-matrix.github.io/dtmapi-R/reference/index.html)
 
 As a representative example of the earlier mentioned functions, see the
 following use of `get_idp_admin_1_data()`:
@@ -98,12 +115,12 @@ idp_admin1_df <- get_idp_admin1_data(CountryName = "Sudan",
 # Display the first few rows of the data frame
 head(idp_admin1_df)
 #>        id              operation admin0Name admin0Pcode admin1Name admin1Pcode
-#> 1 4277072        Darfur conflict      Sudan         SDN  Blue Nile        SD08
-#> 2 4277073        Darfur conflict      Sudan         SDN  Blue Nile        SD08
-#> 3 4277074        Darfur conflict      Sudan         SDN  Blue Nile        SD08
-#> 4 4277075        Darfur conflict      Sudan         SDN  Blue Nile        SD08
-#> 5 4255941 Armed Clashes in Sudan      Sudan         SDN  Blue Nile        SD08
-#> 6 4255942 Armed Clashes in Sudan      Sudan         SDN  Blue Nile        SD08
+#> 1 4743857        Darfur conflict      Sudan         SDN  Blue Nile        SD08
+#> 2 4743858        Darfur conflict      Sudan         SDN  Blue Nile        SD08
+#> 3 4743859        Darfur conflict      Sudan         SDN  Blue Nile        SD08
+#> 4 4743860        Darfur conflict      Sudan         SDN  Blue Nile        SD08
+#> 5 4722729 Armed Clashes in Sudan      Sudan         SDN  Blue Nile        SD08
+#> 6 4722730 Armed Clashes in Sudan      Sudan         SDN  Blue Nile        SD08
 #>   numPresentIdpInd       reportingDate yearReportingDate monthReportingDate
 #> 1            81693 2021-03-30T00:00:00              2021                  3
 #> 2           130958 2021-12-31T00:00:00              2021                 12
@@ -174,8 +191,8 @@ head(operations_df)
 ## User Guide
 
 The information given here is further elaborated on in the user guide to
-getting started with `dtmapi`, which is available through the panel at
-the top of this page.
+getting started with `dtmapi`, which is accessible through
+`vignette("user_guide")`.
 
 ## Source Code
 

_pkgdown.yml

@@ -18,4 +18,4 @@ navbar:
       href: reference/index.html
 
 development:
-  mode: auto
+  mode: release