Merge pull request #44 from tidy-intelligence/christophscheuch-patch-2

Update docs & add pkgdown website

.Rbuildignore

@@ -12,3 +12,6 @@
 ^\.github$
 ^.lintr$
 ^vignettes/*_files$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$

.github/workflows/pkgdown.yaml

@@ -0,0 +1,49 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+name: pkgdown.yaml
+
+permissions: read-all
+
+jobs:
+  pkgdown:
+    runs-on: ubuntu-latest
+    # Only restrict concurrency for non-PR jobs
+    concurrency:
+      group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::pkgdown, local::.
+          needs: website
+
+      - name: Build site
+        run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
+        shell: Rscript {0}
+
+      - name: Deploy to GitHub pages 🚀
+        if: github.event_name != 'pull_request'
+        uses: JamesIves/[email protected]
+        with:
+          clean: false
+          branch: gh-pages
+          folder: docs

.gitignore

@@ -5,3 +5,4 @@
 inst/doc
 /doc/
 /Meta/
+docs

DESCRIPTION

@@ -3,16 +3,19 @@ Package: wbwdi
 Title: Work seamlessly with World Bank World Development Indicators (WDI)
 Version: 0.1.0
 Authors@R: c(
-    person("Christoph", "Scheuch", , "[email protected]", role = c("aut", "cre", "cph"),
-           comment = c(ORCID = "0009-0004-0423-6819"))
-  )
-Description: A modern, flexible interface for accessing the World Bank’s World Development Indicators 
-  (WDI) API <https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation>. 
-  'wbwdi' allows users to download, process, and analyze WDI indicators for multiple geographies and specific time periods. 
-  The package is designed to work seamlessly with International Debt Statistics (IDS) provided through the 'wbids' package.
+    person("Christoph", "Scheuch", , "[email protected]", 
+            role = c("aut", "cre", "cph"),
+            comment = c(ORCID = "0009-0004-0423-6819"))
+    )
+Description: Access and analyze the World Bank’s World Development Indicators 
+  (WDI) using the corresponding API <https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation>. 
+  WDI provides more than 24,000 country or region-level indicators for various
+  contexts. 'wbwdi' enables users to download, process and work with WDI
+  series across multiple geographies and time periods. 
 License: MIT + file LICENSE
-URL: https://github.com/tidy-intelligence/r-wbwdi
-BugReports: https://github.com/tidy-intelligence/r-wbwdi/issues
+Encoding: UTF-8
+Roxygen: list(markdown = TRUE)
+RoxygenNote: 7.3.2
 Depends: 
     R (>= 4.1)
 Imports:
@@ -27,15 +30,8 @@ Suggests:
     curl,
     knitr,
     rmarkdown,
-    testthat (>= 3.2.0)
+    testthat (>= 3.0.0)
 Config/testthat/edition: 3
-Encoding: UTF-8
-LazyData: true
-Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.2
-VignetteBuilder: 
-    knitr
-Remotes:  
-    r-lib/devtools,
-    r-lib/lintr,
-    REditorSupport/languageserver
+URL: https://github.com/tidy-intelligence/r-wbwdi, https://tidy-intelligence.github.io/r-wbwdi/
+BugReports: https://github.com/tidy-intelligence/r-wbwdi/issues
+VignetteBuilder: knitr

README.Rmd

@@ -20,13 +20,15 @@ knitr::opts_chunk$set(
 )
 ```
 
-The goal of 'wbwdi' is to provide a modern, flexible interface for accessing the World Bank’s [World Development Indicators (WDI) API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation) through R. 'wbwdi' allows users to download, process, and analyze WDI indicators for multiple geographies and specific time periods. The package is designed to work seamlessly with International Debt Statistics (IDS) provided through the 'wbids' package and the Python library ['wbwdi'](https://github.com/tidy-intelligence/py-wbwdi).
+`wbwdi` is an R package to access and analyze the World Bank’s World Development Indicators (WDI) using the corresponding [API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation). WDI provides more than 24,000 country or region-level indicators for various contexts. `wbwdi` enables users to download, process and work with WDI series across multiple geographies and time periods. 
+
+The package is designed to work seamlessly with International Debt Statistics (IDS) provided through the [`wbids`](https://github.com/Teal-Insights/r-wbids) package and shares its syntax with its sibling Python library [`wbwdi`](https://github.com/tidy-intelligence/py-wbwdi).
 
 This package is a product of Christoph Scheuch and not sponsored by or affiliated with the World Bank in any way, except for the use of the World Bank WDI API.
 
 ## Installation
 
-You can install the development version of 'wbwdi' like this:
+You can install the development version of `wbwdi` like this:
 
 ``` r
 pak::pak("tidy-intelligence/r-wbwdi")
@@ -100,10 +102,10 @@ wdi_search(
 
 ## Relation to existing packages
 
-The most important difference to existing packages is that 'wbwdi' is designed to (i) have a narrow focus on World Bank Development Indicators, (ii) have a consistent interface with other R packages (e.g., 'wbids'), and (iii) have a shared interface with Python libraries (e.g. ['py-wbwdi'](https://github.com/tidy-intelligence/py-wbwdi)). 'wbwdi' also refrains from using cached data because this approach frequently leads to problems for users to to outdated caches and uses 'httr2' to manage API requests. 
+The most important difference to existing packages is that `wbwdi` is designed to (i) have a narrow focus on World Bank Development Indicators, (ii) have a consistent interface with other R packages (e.g., `wbids`), and (iii) have a shared interface with Python libraries (e.g., [`wbwdi`](https://github.com/tidy-intelligence/py-wbwdi)). `wbwdi` also refrains from using cached data because this approach frequently leads to problems for users to to outdated caches and uses `httr2` to manage API requests. 
 
 The relation to the most popular existing R packages are:
 
-- [WDI](https://cran.r-project.org/web/packages/WDI/index.html): uses cached data by default, does not allow downloading meta data from the WDI API (e.g., languages, sources, topics), does neither use 'httr' nor 'httr2'.
-- [worldbank](https://cran.r-project.org/web/packages/worldbank/index.html): does not have a narrow focus because it includes the Poverty and Inequality Platform and Finances One API.
-- [wbstats](https://cran.r-project.org/web/packages/wbstats/index.html): uses cached data by default, does not use 'httr2'.
+- [`WDI`](https://cran.r-project.org/web/packages/WDI/index.html): uses cached data by default, does not allow downloading meta data from the WDI API (e.g., languages, sources, topics), does neither use 'httr' nor `httr2`.
+- [`worldbank`](https://cran.r-project.org/web/packages/worldbank/index.html): only allows the download of a single indicator with each function call and does not have a narrow focus because it includes the Poverty and Inequality Platform and Finances One API.
+- [`wbstats`](https://cran.r-project.org/web/packages/wbstats/index.html): uses cached data by default, does not use `httr2`.

README.md

@@ -12,22 +12,26 @@ coverage](https://codecov.io/gh/tidy-intelligence/r-wbwdi/graph/badge.svg)](http
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
-The goal of ‘wbwdi’ is to provide a modern, flexible interface for
-accessing the World Bank’s [World Development Indicators (WDI)
-API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation)
-through R. ‘wbwdi’ allows users to download, process, and analyze WDI
-indicators for multiple geographies and specific time periods. The
-package is designed to work seamlessly with International Debt
-Statistics (IDS) provided through the ‘wbids’ package and the Python
-library [‘wbwdi’](https://github.com/tidy-intelligence/py-wbwdi).
+`wbwdi` is an R package to access and analyze the World Bank’s World
+Development Indicators (WDI) using the corresponding
+[API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation).
+WDI provides more than 24,000 country or region-level indicators for
+various contexts. `wbwdi` enables users to download, process and work
+with WDI series across multiple geographies and time periods.
+
+The package is designed to work seamlessly with International Debt
+Statistics (IDS) provided through the
+[`wbids`](https://github.com/Teal-Insights/r-wbids) package and shares
+its syntax with the Python library
+[‘py-wbwdi’](https://github.com/tidy-intelligence/py-wbwdi).
 
 This package is a product of Christoph Scheuch and not sponsored by or
 affiliated with the World Bank in any way, except for the use of the
 World Bank WDI API.
 
 ## Installation
 
-You can install the development version of ‘wbwdi’ like this:
+You can install the development version of `wbwdi` like this:
 
 ``` r
 pak::pak("tidy-intelligence/r-wbwdi")
@@ -108,23 +112,24 @@ wdi_search(
 
 ## Relation to existing packages
 
-The most important difference to existing packages is that ‘wbwdi’ is
+The most important difference to existing packages is that `wbwdi` is
 designed to (i) have a narrow focus on World Bank Development
 Indicators, (ii) have a consistent interface with other R packages
-(e.g., ‘wbids’), and (iii) have a shared interface with Python libraries
+(e.g., `wbids`), and (iii) have a shared interface with Python libraries
 (e.g. [‘py-wbwdi’](https://github.com/tidy-intelligence/py-wbwdi)).
-‘wbwdi’ also refrains from using cached data because this approach
+`wbwdi` also refrains from using cached data because this approach
 frequently leads to problems for users to to outdated caches and uses
-‘httr2’ to manage API requests.
+`httr2` to manage API requests.
 
 The relation to the most popular existing R packages are:
 
-- [WDI](https://cran.r-project.org/web/packages/WDI/index.html): uses
+- [`WDI`](https://cran.r-project.org/web/packages/WDI/index.html): uses
   cached data by default, does not allow downloading meta data from the
   WDI API (e.g., languages, sources, topics), does neither use ‘httr’
-  nor ‘httr2’.
-- [worldbank](https://cran.r-project.org/web/packages/worldbank/index.html):
-  does not have a narrow focus because it includes the Poverty and
+  nor `httr2`.
+- [`worldbank`](https://cran.r-project.org/web/packages/worldbank/index.html):
+  only allows the download of a single indicator with each function call
+  and does not have a narrow focus because it includes the Poverty and
   Inequality Platform and Finances One API.
-- [wbstats](https://cran.r-project.org/web/packages/wbstats/index.html):
-  uses cached data by default, does not use ‘httr2’.
+- [`wbstats`](https://cran.r-project.org/web/packages/wbstats/index.html):
+  uses cached data by default, does not use `httr2`.

_pkgdown.yml

@@ -0,0 +1,4 @@
+url: https://tidy-intelligence.github.io/r-wbwdi/
+template:
+  bootstrap: 5
+

renv.lock

@@ -52,13 +52,13 @@
     },
     "curl": {
       "Package": "curl",
-      "Version": "6.0.0",
+      "Version": "6.0.1",
       "Source": "Repository",
       "Repository": "CRAN",
       "Requirements": [
         "R"
       ],
-      "Hash": "ff51697d9205fe715f29e7171e874c6e"
+      "Hash": "e8ba62486230951fcd2b881c5be23f96"
     },
     "dplyr": {
       "Package": "dplyr",

vignettes/data-model.Rmd

@@ -11,7 +11,7 @@ vignette: >
 
 The diagram below shows the data model of the `wbwdi` package. In our design, we primarily have R users in mind, particularly those who rely heavily on the popular data manipulation packages `dplyr` and `data.table`. For these users, having consistent and descriptive primary key column names across different tables (e.g., `geography_id`, `series_id`) simplifies writing joins across tables, reduces the risk of column name conflicts, and avoids ambiguity.
 
-```{r, out.width = "100%", echo=FALSE}
+```{r, out.width = "100%", echo=FALSE, fig.alt = "A visual representation of the data model behind the 'wbwdi' R package."}
 knitr::include_graphics("images/data-model.png")
 ```
 

vignettes/using-wbwdi.Rmd

@@ -20,15 +20,7 @@ library(wbwdi)
 
 The `wbwdi` package provides a modern and flexible interface for accessing the World Bank’s [World Development Indicators (WDI)](https://datatopics.worldbank.org/world-development-indicators/). With `wbwdi`, you can download data for multiple indicators and geographies in a single function call, benefit from progress bars, and receive the output in a tidy data format, making it ideal for further analysis with other data sources.
 
-## Installation
-
-To install the development version of `wbwdi`, use:
-
-```{r eval=FALSE}
-pak::pak("tidy-intelligence/r-wbwdi")
-```
-
-## Listing supported indicators
+## Listing Supported Indicators
 
 The `wbwdi` package allows you to retrieve a full list of all supported indicators from the World Bank [Indicators API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation). Each indicator is accompanied by metadata such as its unit of measurement, source, and associated topics.
 
@@ -48,11 +40,11 @@ To get the list of languages supported by the API, call:
 wdi_get_languages()
 ```
 
-Note that not all indicators might be translated into all languages. 
+Note that not all indicators and their columns might be translated into all languages. 
 
-## Listing supported geographies
+## Listing Supported Geographies
 
-You can retrieve a list of all geographies supported by the World Bank API along with metadata such as region, administrative region, income level, and lending type.
+You can retrieve a list of all geographies supported by the World Bank API along with metadata such as region, administrative region, income level, and lending type. Note that a geography might be a country or a region, hence the more general table name.
 
 ```{r}
 wdi_get_geographies()
@@ -64,7 +56,7 @@ This information can also be requested in other languages. For example, to view
 wdi_get_geographies(language = "zh")
 ```
 
-### Downloading indicator data
+### Downloading Indicator Data
 
 With `wbwdi`, you can download indicator data for multiple geographies and indicators in a single function call. The function returns a tidy data frame with country, indicator, date, and value columns.
 
@@ -86,7 +78,17 @@ wdi_get(
 )
 ```
 
-## Other helper functions
+If you want to retrieve the indicators in a wide format, you can use the corresponding parameter.
+
+```{r}
+wdi_get(
+  geographies = "US",
+  indicators = c("NY.GDP.PCAP.KD", "SP.POP.TOTL"),
+  format = "wide"
+)
+```
+
+## Other Helper Functions
 
 You can fetch a list of all supported regions, sources, topics and lending types, respectively, using the corresponding helper function:
 
@@ -97,7 +99,7 @@ wdi_get_topics()
 wdi_get_lending_types()
 ```
 
-If you want to search for specific keywords among indicators or other data sources, you can use the RStudio or Positron data explorer. Alternatively, this package comes with a helper function:
+If you want to search for specific keywords among indicators or other data sources, you can use the built-in RStudio data frame viewing functionality or the [Positron Data Explorer](https://positron.posit.co/data-explorer.html). Alternatively, this package comes with a helper function:
 
 ```{r}
 indicators <- wdi_get_indicators()