From f1eae9077c7eaa804e622260face365d97d2ec98 Mon Sep 17 00:00:00 2001 From: Anna Petrasova Date: Thu, 15 May 2025 15:30:01 -0400 Subject: [PATCH 1/5] Add CONTRIBUTING.md --- CONTRIBUTING.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..99a8318 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,127 @@ +# Contributing to GRASS tutorials + +We welcome various contributions — fixing a typo, improving clarity, or adding a new tutorial. +Not sure where to begin? [Open an issue](https://github.com/OSGeo/grass-tutorials/issues) to start a conversation. + +--- + +## Getting started + +1. **Fork and clone** the repository. Then follow the +[GitHub guide](https://grass.osgeo.org/grass-devel/manuals/github_guide.html) for the GRASS repository and adjust the workflow for this repository. + +2. **Install Quarto** (if you haven’t already), see + +3. **Preview the site locally:** + + ```sh + quarto preview + ``` + + This launches a local server and opens a live preview in your browser. + +4. **Create or edit tutorials:** + + Tutorials are written in Markdown (.qmd) with YAML front matter. + + Add your tutorial to the appropriate section (e.g., ./content/tutorials/mytutorials). + +## Writing a tutorial + +Give your audience some context, for example include what topics does +the tutorial cover, what are the prerequisites, and so on. + +Use Quarto's [guide](https://quarto.org/docs/guide/) to learn how to write +Quarto documents and learn [Markdown syntax](https://quarto.org/docs/authoring/markdown-basics.html). + +For example, include GRASS commands in fenced code blocks: + +```` markdown +```{python} +gs.run_command("g.region", raster="elevation") +``` +```` + +You can use [tabsets](https://quarto.org/docs/output-formats/html-basics.html#tabsets) +to show how to run GRASS commands in command line and in Python: + +```` markdown +::: {.panel-tabset group="language"} + +## Command line + +```{bash} +g.region raster=elevation +``` + +## Python + +```{python} +gs.run_command("g.region", raster="elevation") +``` + +::: +```` + +Display notes: + +::: {.callout-note title="Setup"} +To run this tutorial locally ... +::: + +## YAML metadata example + +Each tutorial must begin with YAML metadata like this: + +```` yaml +--- +title: "Computing slope from elevation data in Python" +author: "Your Name" +date: "2025-05-15" +description: "Learn how to derive slope from elevation data in GRASS in a Jupyter Notebook." +categories: ["beginner", "geomorphometry", Python] +thumbnail: slope_thumbnail.webp +format: + ipynb: default + html: + toc: true + code-tools: true + code-copy: true + code-fold: false +engine: jupyter +execute: + eval: false +jupyter: python3 +--- + +```` + +Use `eval: false` so that Quarto doesn't run the code during building of the website. +Specifying format `ipynb: default` will create a Jupyter notebook during the build process and link it from the tutorial page. + +## Images + +Beatiful images and graphics make tutorials stand out! +Make sure the images have *sufficient resolution*. +At the same time, their size should not be too big to load quickly, try to keep it under 200 KB or so. We recommend using *webp* format. + +``` markdown +![Slope map](slope.webp) +``` + +Each tutorial needs to have at least one image that can be used on the main page as a thumbnail. +You can either specify it in the YAML header (`thumbnail: image.webp`) or add `{.preview-image}` to the image. + +``` markdown +![Slope map](slope.webp){.preview-image} +``` + +## Submitting your contribution + +Check your markdown with a [linter](https://dlaa.me/markdownlint/) and fix as many issues as you can. This will help keeping the tutorials consistent. + +Follow the [GitHub guide](https://grass.osgeo.org/grass-devel/manuals/github_guide.html) to submit your tutorial. +Once you sumbmit a PR, the CI pipeline will build your tutorial, so you and a reviewer can check if everything is ok. Once a reviewer approves, your PR will be merged. + +--- +Thanks for helping us build better educational resources for the GRASS community! From 6f053923fba715a4965741f9adcabe70facecb05 Mon Sep 17 00:00:00 2001 From: Anna Petrasova Date: Thu, 15 May 2025 15:33:38 -0400 Subject: [PATCH 2/5] fixes --- CONTRIBUTING.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99a8318..dc40908 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,9 +65,11 @@ gs.run_command("g.region", raster="elevation") Display notes: +``` markdown ::: {.callout-note title="Setup"} To run this tutorial locally ... ::: +``` ## YAML metadata example @@ -120,8 +122,11 @@ You can either specify it in the YAML header (`thumbnail: image.webp`) or add `{ Check your markdown with a [linter](https://dlaa.me/markdownlint/) and fix as many issues as you can. This will help keeping the tutorials consistent. -Follow the [GitHub guide](https://grass.osgeo.org/grass-devel/manuals/github_guide.html) to submit your tutorial. -Once you sumbmit a PR, the CI pipeline will build your tutorial, so you and a reviewer can check if everything is ok. Once a reviewer approves, your PR will be merged. +Follow the [GitHub guide](https://grass.osgeo.org/grass-devel/manuals/github_guide.html) +(adapt it to this repo) to submit your tutorial. +Once you sumbmit a PR, the CI pipeline will build your +tutorial, so you and a reviewer can check if everything is ok. +When a reviewer approves, your PR will be merged soon. --- Thanks for helping us build better educational resources for the GRASS community! From 461356a00b235ce16a07da78b149bda05617e24c Mon Sep 17 00:00:00 2001 From: Anna Petrasova Date: Thu, 15 May 2025 15:34:58 -0400 Subject: [PATCH 3/5] add link to README --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 95755e8..00afffa 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ explained in the [GitHub guide](https://github.com/OSGeo/grass/blob/main/doc/development/github_guide.md) written for OSGeo/grass repository, so just adjust it for this repository. +See [CONTRIBUTING.md](CONTRIBUTING.md) for more details. + ## License The content in this repository is dual-licensed under the From 59072cc12bacc7ecae99d1b2a1f2d6057d4a4741 Mon Sep 17 00:00:00 2001 From: Anna Petrasova Date: Thu, 15 May 2025 15:38:16 -0400 Subject: [PATCH 4/5] more notes --- CONTRIBUTING.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dc40908..754cf11 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -98,8 +98,13 @@ jupyter: python3 ```` -Use `eval: false` so that Quarto doesn't run the code during building of the website. -Specifying format `ipynb: default` will create a Jupyter notebook during the build process and link it from the tutorial page. +Notes: + +- Use appropriate categories (tags), include whether the tutorial is *beginner*, *intermediate*, or *advanced*. + +- Use `eval: false` so that Quarto doesn't run the code during building of the website. + +- Specifying format `ipynb: default` will create a Jupyter notebook during the build process and link it from the tutorial page. ## Images From 8545f6e677c4e3cf23fff76f00f6c5b250f831d8 Mon Sep 17 00:00:00 2001 From: Anna Petrasova Date: Thu, 15 May 2025 16:59:07 -0400 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Veronica Andreo --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 754cf11..d9cf036 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -100,7 +100,7 @@ jupyter: python3 Notes: -- Use appropriate categories (tags), include whether the tutorial is *beginner*, *intermediate*, or *advanced*. +- Use appropriate categories (tags), include whether the tutorial is for *beginner*, *intermediate*, or *advanced* users. - Use `eval: false` so that Quarto doesn't run the code during building of the website. @@ -108,7 +108,7 @@ Notes: ## Images -Beatiful images and graphics make tutorials stand out! +Beautiful images and graphics make tutorials stand out! Make sure the images have *sufficient resolution*. At the same time, their size should not be too big to load quickly, try to keep it under 200 KB or so. We recommend using *webp* format. @@ -129,6 +129,7 @@ Check your markdown with a [linter](https://dlaa.me/markdownlint/) and fix as ma Follow the [GitHub guide](https://grass.osgeo.org/grass-devel/manuals/github_guide.html) (adapt it to this repo) to submit your tutorial. +You should **only commit the .qmd file and images**. Once you sumbmit a PR, the CI pipeline will build your tutorial, so you and a reviewer can check if everything is ok. When a reviewer approves, your PR will be merged soon.