documentation updates

[GregorDeCillia]

This PR will provide some documentation updates regarding the new Open Government Data functionalities

• [x] New pkgdown articles in vignettes/
• [x] Update existing articles in vignettes/
• [x] Overhaul documentation in man/
• [x] Refactor exports and other parts of the NAMESPACE

[GregorDeCillia]

The commits so far should cover all necessary changes to R/ except some functions for the resources article.

[GregorDeCillia]

Missing articles

• [x] tabulation article
• [x] caching article
• [x] available datasets article

Additional TODOs

• [x] update contents of pkgdown/
• [x] add missing functions od_downloads() and od_cache_summary()
• [x] print() method for the return value of od_json()

[GregorDeCillia]

Reminder to self: The current articles assume that you have a persistent cache set up in ~/.cache/STATcubeR/open_data. There might be room for improvement.

[GregorDeCillia]

Github is currently experiencing some issues so I'll take the time to summarize the progress so far This branch is now "feature complete". There are two changes that will make sure devtools::check() runs without errors

• [x] remove @examples in the now internal function sc_meta()
• [x] apply method consistency print(x, ...) to print.od_json

After that, I need to check if the old articles about the STATcube REST API are still working properly. They did some days ago so only minor changes are not to be expected.

[GregorDeCillia]

The current version passes devtools::check() with no errors, warnings or notes. Furthermore, the pkgdown site can be rendered without any issues.

About the links

• Inside of our firewall, the pkgdown docs are available at http://rstudiodevweb.statistik.local/rpkgs/dev/STATcubeR/dev/ (so much devs!) and they will be updated regularly.
• The external docs at https://statistikat.github.io/STATcubeR/dev/ will recieve updates less frequently.
• When this branch is merged, the docs will be uploaded to https://statistikat.github.io/STATcubeR/

[GregorDeCillia]

@bernhard-da if you want to do updates on the docs, build them locally and transfer them to the webserver with our internal useSTAT package.

pkgdown::build_site()
useSTAT:::deploy_pkgdown_dev()

I'd recommend to set up caching for development by modifying .Renviron. Otherwise, you'll download the same cubes many times when building the articles and man pages.

usethis::edit_r_environ()

STATCUBE_KEY       = YOUR_API_KEY_GOES_HERE
STATCUBE_CACHE     = TRUE
OD_CACHE_DIR       = "~/.cache/STATcubeR/open_data/"
STATCUBE_CACHE_DIR = "~/.cache/STATcubeR/api/"

On that note - some possible improvements

• [ ] Make it possible to set just one environment variable that determines both cache directories
• [ ] Document and export STATcube caching
• [x] use UPPER_CASE for od_cache_dir for consistency

[GregorDeCillia]

An updated version of the docs is available at https://statistikat.github.io/STATcubeR/dev/

[GregorDeCillia]

@bernhard-da could you please provide some feedback about the current state of the pkgdown documentation? I don't think it needs to be perfect but having a second opinion would be very useful.

Some remarks about the links

• The links from the landing page (README) to the articles is missing a dev/ in the url. This will be resolved when this PR is merged and the pkgdown site is deployed to https://statistikat.github.io/STATcubeR/
• The links to the gh source files might not work because they always link to master
• All other links are relative and should work without any issues

I suggest you start with article index and the reference index and decide if we should update any names or descriptions. The articles linked in the navbar are the most important ones.

I added you as an author and linked to your gh-account. Just let me know if this is okay https://github.com/statistikat/STATcubeR/blob/8c564510aac366794b67e8ddffe4eda60e8444e2/pkgdown/_pkgdown.yml#L13-L14

[bernhard-da]

@GregorDeCillia very nice work, all articles are very well written and very clear; just some very minor things

• https://statistikat.github.io/STATcubeR/dev/index.html -> link to setup-article does not work (is https://statistikat.github.io/STATcubeR/articles/articles/sc_key.html and should be https://statistikat.github.io/STATcubeR/dev/articles/sc_key.html
• in https://statistikat.github.io/STATcubeR/dev/articles/sc_table.html you could remove the part with the raw response as you will probably remove it in the future I guess

[GregorDeCillia]

@bernhard-da thank you. The link is now fixed in the VCS. Yes: the sc_table class is still a little bit weird: see the full class documentation. It is probably a good idea not to mention that in the introduction docs.

I am not sure if $raw will be fully removed because there are certain parts that are "lost" when we do so, but it is certainly something for advanced users.

[GregorDeCillia]

Maybe this PR should also be used to refactor the dependencies

Imports

• [ ] magrittr is not really necessary but makes for prettier code
• [x] httr is needed for API calls.
• [x] jsonlite is necessary to parse the httr responses.

Suggests

• [x] rmarkdown is pretty much irrelevant since the vignettes are only available online
• [x] data.tree provides a print method for schema responses but nothing else.
• [x] rstudioapi allows sc_table()$json$edit but nothing else
• [ ] xml2 is only used in od_list to do some webscraping
• [x] pillar is just used in .onLoad() to register pretty printing in case the pkg is available

I'm still wondering why devtools::check() doesn't complain about {R6} not being in the dependencies.

[GregorDeCillia]

• Version updated to 0.2.3
• gh-pages deployment at https://statistikat.github.io/STATcubeR/