Add and update guide on how to add a tutorial

[peterdesmet]

Rather than a section in the Software development, it was decided to create a separate guide on how to contribute content to the website. The instructions are different for documentation pages that are maintained in this repo and those maintained elsewhere.

• Create separate guide src/content/docs/guides/contributing.md
• Describe workflow: add/edit -> PR -> review -> update
• Describe 3 different ways of adding/updating tutorials
  • md as source
  • Rmd as source (see Add and update guide on how to add a tutorial #63 (comment))
  • external vignette as source
• Describe maintenance
  • How does website work (Astrodoc)
  • What should maintainers do periodically (build vignettes)
• Link to guide
  • From software dev guide last chapter
  • From CONTRIBUTING.md
  • From README

[LBreugelmans]

Great, I was looking for this. Is the idea to link to the sections of the pkgdown site for repo's?

[peterdesmet]

For now, we link (see the gcube page). But we plan to change that in the near future and copy all pkgdown tutorials to the documentation site, so they can be found by the site search (see this test). In order to keep them in sync, @sannegovaert will develop a small R package to do that.

So I recommend to wait a bit for now, but do add your tutorials to the Google spreadsheet Laura shared, so we are aware of them. :-)

[wlangera]

I will add this here if that's fine:

You can add a tutorial by creating a Markdown file (e.g. src/content/docs/guides/software-development.md) in this repository.
The website will automatically incorporate these Markdown files in the site.

A way to add R Markdown files to the documentation website is to use the YAML header below, where you can change the title, label and order according to your tutorial.
When you knit the R Markdown, a Markdown file is created in the same folder which will be incorporated in the documentation website automatically (see note after YAML header, adapt to your file name).

I have also provided knitr chunck options. Figures are stored in the public\guides folder in a specific subfolder per tutorial.
Adapt b3verse subfolder name to one for your new tutorial.

---
title: Welcome to the b3verse!
sidebar:
  label: The b3verse
  order: 6
knit: (function(inputFile, ...) {
  knitr::knit(
    input = inputFile,
    output = gsub("Rmd$", "md", inputFile)) })
---

<!-- b3verse.md is generated from b3verse.Rmd Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = file.path("../../../..", "public", "guides", "b3verse", "/"),
  out.width = "80%",
  dpi = 300
)
`` `

[peterdesmet]

@sannegovaert could you take a first stab at the guide (before end of this year)?

[sannegovaert]

This is done in the readme, should this also be added to the website as a guide?

[peterdesmet]

Yeah, we now have all the content in the README, but I still think it makes sense to have it on the website. So I still suggest:

Guide

• src/content/docs/guides/contributing.md
• Title: "Contributing"
• Copy the entire "Usage" and "Updating a page" section from the README
• Rephrase "the website" to "this website"

README

• Remove "Usage" and "Updating a page" section (so we don't have it in two places)
• Extend first sentence to:

This repository contains the source files for the B-Cubed documentation website. The website makes use of Astro (a web framework) and Starlight (a documentation theme for Astro) to transform markdown and configuration files to a static website.

Contributing

See the contributing guide.

• Keep the "Repo structure" section

CONTRIBUTING.md

• Add a "See the contributing guide.