Vignettes as tutorials

[LienReyserhove]

Description

This PR contains the vignettes as tutorials, as described in #262 All vignettes can be found in the tutorials/content/tutorials folder. One tutorial equals one vignette. The name of the file follows the convention vignette + package_name+ vignette_name. The structure of the index.md uses the following structure:

---
title: "..."
description: "Vignette for the R package ...."
authors: ...
date: ...
categories: ["r"]
tags: ["r", "vignette", ...]
output: 
    md_document:
        preserve_yaml: true
        variant: markdown_github
---

See the vignette/tutorial at <link>

@florisvdh @peterdesmet @ThierryO the revision is all yours

Task list

• [x] My tutorial or article is placed in a subfolder of tutorials/content
• [x] The filename of my tutorial or article is index.md. In case of an Rmarkdown tutorial I have knitted my index.Rmd to index.md (both files are pushed to the repo).
• [x] I have included tags in the YAML header (see the tags listed in the tutorials website side bar for tags that have been used before)
• [x] I have added categories to the YAML header and my category tags are from the list of category tags

Previewing the pull request

Thanks to GitHub Actions, an artifact (=zip file) of the rendered website is automatically created for each pull request.

[ThierryO]

Instead of linked to the individual vignettes, we could link to https://inbo.r-universe.dev/ui#articles instead.

[ElsLommelen]

@ThierryO When linking to inbo.r-universe, to what extend can we find these manuals when using the tags? For instance, I would like to query the inboveg database using R and I don't know how to do this. So I search on the tutorials website how to do it. At the moment there is still an old copy of the inbodb package vignette on inboveg that explains this, and that pops up directly when searching on the subject of databases, but if this is deleted, how will a visitor of the tutorials site be aware of the fact that there is a package with specific functions to solve his problem?

Maybe it is not necessary to have such link to all vignettes of all packages (e.g. to me it seems less relevant for specific non-coding-related subjects such as as package dhcurve), and maybe links to vignettes on related subjects can be grouped on one site (e.g. put all vignettes on querying INBO databases together, or all vignettes that have the same combination of tags), but for subjects that are typically searched for on the tutorials website, to me it seems useful for tutorials site visitors to at least learn that an INBO package on this subject exists. (If I don't have experience with coding on a specific topic, e.g. query databases or manipulate raster geodata, I would search on the tutorials site, rather than checking if INBO has a package on it for any chance.)

On the other hand I agree with @ThierryO that it may not be necessary to link to every single vignette and give all vignette a separate site, which will certainly become a disaster for maintenance. In inbodb, probably 2 new vignettes will be added this year, so it seems easier for maintenance to just refer to inbo.github.io/inbodb where vignettes for different databases can be found (I plan on giving the vignettes more visibility on this main page). Probably a similar exercise can be done for other vignettes and packages?

So I think it is certainly helpful to have these tutorials that refer to package( vignette)s, but maybe try to refer to packages rather than vignettes (if the subject is related), and try to group different links on one page as much as possible.

[peterdesmet]

I cannot reach https://inbo.r-universe.dev/ui#articles -> https://github.com/inbo/universe/issues/6

[peterdesmet]

The goals of this PR was to elevate the work we collectively put in vignettes and make them easily accessible as tutorials via the Tutorials website. As @ElsLommelen explains, it allows to search for a topic and find vignettes as well as regular tutorials on that subject, which wouldn't work if we just refer to r-universe.

Regarding maintenance, I don't think that's going to be too bad, especially if we only do it once a year (@LienReyserhove correct me if I'm wrong). As @ElsLommelen suggests, we could bundle Vignettes for some packages on a single page, but that also comes with the cognitive burden (during maintenance) of having to decide which ones to bundle, what authors, topics, etc. to apply, ... with little added benefit.

So, until this becomes unwieldy, I like the approach of having one Vignette = one Tutorial.

[ElsLommelen]

we could bundle Vignettes for some packages on a single page, but that also comes with the cognitive burden (during maintenance) of having to decide which ones to bundle, what authors, topics, etc. to apply, ... with little added benefit.

One advantage for the website visitor to bundle vignettes is to avoid having long lists after searching for a topic (tag), each of it referring to a separate page with just one link.

Easiest would be to bundle topics that have got the same tags, but indeed: authors. Maybe mention only @LienReyserhove as an author because she has composed the pages? The package or vignette authors are mentioned at the linked sites, I suppose?

Anyway, I leave it up to the maintainer(s) to decide if this small advantage outweighs the extra effort to bundle vignettes.

[peterdesmet]

@florisvdh I cannot use markdown in titles, so it will have to be:

inborutils: GBIF scientific name matching

Not

inborutils: GBIF scientific name matching

Here's a comparison between the two approach (as part of description vs part of title):

Do you still prefer to prepend titles with the package name?

[florisvdh]

Thanks for solving the author IDs!

Sure, I still would prepend the titles with the package name.

What about:

This is the UTF-8 'package' character (https://www.utf8icons.com/character/128230/package).

See 792a016a for the syntaxis used, if you like this (mind the spaces).

[peterdesmet]

I like the emoji approach, but would maybe use it on the description, so it doesn't become to visually overloading in the overview of titles. Compare:

Makes it also easier to copy/paste without errors.

[florisvdh]

Two more variations:

(a1aadbdb)

(4b6d48cc)

Corresponding tutorial pages of the three variations:

Screenshots

  

[florisvdh]

Yes, that makes it less overloaded in the tutorial page too:

[florisvdh]

Note that currently two pull requests exist to amend this PR:

• PR #294 (@ElsLommelen deleting a vignette)
• PR #297 (me adding a vignette)

[ElsLommelen]

Note that currently two pull requests exist to amend this PR:

@florisvdh Just a suggestion: to be sure it is not forgotten, I added a 'requested changes' review. ;-)

[peterdesmet]

All issue and feedback resolved, thanks for the input! A huge thanks to @LienReyserhove 👏👏👏 for hunting down all the vignettes, translating these into tutorials, and weathering the feedback and format changes. 😄 @LienReyserhove I have also updated the spreadsheet to reflect the current state.

[florisvdh]

Just spotted a dwelling 📦:

[peterdesmet]

@ElsLommelen no need for a thorough review (we all had a check already, especially @florisvdh), but your approval is needed before this PR can be merged. 😄