From f983c7642cea30e850df993fa0875ce0211c9a89 Mon Sep 17 00:00:00 2001 From: Floris Vanderhaeghe Date: Mon, 10 Feb 2025 10:47:33 +0100 Subject: [PATCH 1/6] Update pull_request_template.md While reviewing https://github.com/inbo/tutorials/pull/356, the instructions of the PR template for reviewing seem to no longer work to render the site from the GHA artifact. With these changes, it seems to work again though, using python -m http.server 8887 --- .github/pull_request_template.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index fd6b6db93..9bdae4a83 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -38,9 +38,9 @@ This provides a way to preview how these updates will look on the website, usefu ### Instructions to preview the updated website 1) On the PR page, you can find a "details" link under "checks - On PR, build the site and ...". Go there, click on the top link in the left sidebar ("Summary"), and download the generated artifact at the bottom of the page. -2) Decompress it and make sure the target directory is called 'tutorials' (you may need to rename it) -3) From the parent directory (just above the `tutorials` folder you created/renamed), run `python -m http.server 8887`, _or_ launch the Google Chrome [Web Server app](https://chrome.google.com/webstore/detail/web-server-for-chrome/ofhbbkphhbklhfoeikjpcbhemlocgigb) and point it at the parent directory. -4) Point your browser to http://localhost:8887/tutorials. +2) Decompress it into a target directory. +3) From the target directory, run `python -m http.server 8887`, _or_ launch the Google Chrome [Web Server app](https://chrome.google.com/webstore/detail/web-server-for-chrome/ofhbbkphhbklhfoeikjpcbhemlocgigb) and point it at the target directory. +4) Point your browser to http://0.0.0.0:8887. 5) Review the updated website. As a contributor, you can push extra commits to update the PR. As a reviewer, you can accept/refuse/comment the PR. **Note: for step 3, you can use any other simple HTTP server to serve the current directory if you don't have a Python 3 environment or Google Chrome available.** From 2f67cb9e50084d5ead3b2b89a5d13c94d28a0b98 Mon Sep 17 00:00:00 2001 From: Falk Mielke Date: Thu, 13 Feb 2025 13:19:23 +0100 Subject: [PATCH 2/6] update_pr_template: introduce --- .github/pull_request_template.md | 9 +++++---- content/create_tutorial/index.md | 4 ++-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9bdae4a83..e4ccf7629 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -28,6 +28,7 @@ for an explanation on how to use task lists--> - [ ] 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). - [ ] I have included `tags` in the YAML header (see the tags listed in the [tutorials website side bar](https://inbo.github.io/tutorials/) for tags that have been used before) - [ ] I have added `categories` to the YAML header and my category tags are from the [list of category tags](https://github.com/inbo/tutorials/blob/master/static/list_of_categories) +- [ ] I have previewed this PR locally (see steps below) and confirmed that the new content renders as expected. ## Previewing the pull request @@ -38,9 +39,9 @@ This provides a way to preview how these updates will look on the website, usefu ### Instructions to preview the updated website 1) On the PR page, you can find a "details" link under "checks - On PR, build the site and ...". Go there, click on the top link in the left sidebar ("Summary"), and download the generated artifact at the bottom of the page. -2) Decompress it into a target directory. -3) From the target directory, run `python -m http.server 8887`, _or_ launch the Google Chrome [Web Server app](https://chrome.google.com/webstore/detail/web-server-for-chrome/ofhbbkphhbklhfoeikjpcbhemlocgigb) and point it at the target directory. -4) Point your browser to http://0.0.0.0:8887. +2) Decompress it into a target directory, e.g. `Downloads/tutorials_preview`. +3) To preview the website, use a program which can serve `http` sites on your local machine. One such option is [the `servr` package](https://github.com/yihui/servr) in R: `& '\C:\Program Files\R\R-4.4.2\bin\Rscript.exe' -e "servr::httd('./tutorials_preview')" -p8887` +4) Point your browser to http://localhost:8887. 5) Review the updated website. As a contributor, you can push extra commits to update the PR. As a reviewer, you can accept/refuse/comment the PR. -**Note: for step 3, you can use any other simple HTTP server to serve the current directory if you don't have a Python 3 environment or Google Chrome available.** +**Note: for step 3, you can use any other simple HTTP server to serve the current directory, e.g. [Python `http.server`](https://docs.python.org/3/library/http.server.html): `python -m http.server 8887 --bind localhost --directory path/to/tutorials_preview`** diff --git a/content/create_tutorial/index.md b/content/create_tutorial/index.md index c7e1ef126..b6e4476df 100644 --- a/content/create_tutorial/index.md +++ b/content/create_tutorial/index.md @@ -172,7 +172,7 @@ Replace all the CAPITAL words with appropriate information: - multiple tags you can pick yourself, all lowercase words. Have a look at the current [wordcloud](https://inbo.github.io/tutorials/tags/) to check which would be useful for your submission. - leave the `output` section as it is -Underneath the last triple dahs (`---`), you can write the tutorial as you like using [markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) and add code chunks to run R code. +Underneath the last triple dash (`---`), you can write the tutorial as you like using [markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) and add code chunks to run R code. As the Rmarkown file will not be part of the website, make sure to click the `knit` button to create the equivalent markdown file (`index.md`) in the same directory: @@ -180,7 +180,7 @@ As the Rmarkown file will not be part of the website, make sure to click the `kn **Notice**: always knit the Rmarkdown file before you start committing the changes! -- `add`/`commit` **both files** to git, cfr. [STEP 2 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#while_editing). You can commit the tutorial all in once or split the commits in different steps, that is up to you. To make sure your work is updated online as well, `push` the tutorial as in [STEP 3 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_3:_push_your_changes_to_github). +- `add`/`commit` **both files** to git, *cfr.* [STEP 2 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#while_editing). You can commit the tutorial all in once or split the commits in different steps, that is up to you. To make sure your work is updated online as well, `push` the tutorial as in [STEP 3 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_3:_push_your_changes_to_github). - When ready, `push` your tutorial a last time and create a `Pull request` to the website maintainers as explained in [STEP 4 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_4:_pull_request_to_add_your_changes_to_the_current_master). After you pull request, your submission will be checked and reviewed. When accepted and merged, you tutorial will be online. From 8060599f88fe28ec106d80d2024a9b66c0a08837 Mon Sep 17 00:00:00 2001 From: Falk Mielke Date: Fri, 14 Feb 2025 11:44:23 +0100 Subject: [PATCH 3/6] update_pr_template: *cf.* consistency Latijns -> italics; https://nl.wikipedia.org/wiki/Cf. --- content/create_tutorial/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/create_tutorial/index.md b/content/create_tutorial/index.md index b6e4476df..fd4f9fa0f 100644 --- a/content/create_tutorial/index.md +++ b/content/create_tutorial/index.md @@ -100,7 +100,7 @@ If it is your first submission using your computer, [clone](https://inbo.github. Next, we use the [git workflow](https://inbo.github.io/git-course/workflow_rstudio.html) to submit the new tutorial: -- Update your code and create a new branch, cfr. [STEP 1 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#option-1a-ill-make-a-new-branch-to-work-with). Provide a useful name for your branch related to the topic of your tutorial, e.g. `r_tidy_data` or `database_query_inboveg` and not ~~`my_tutorial`~~. +- Update your code and create a new branch, *cf.* [STEP 1 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#option-1a-ill-make-a-new-branch-to-work-with). Provide a useful name for your branch related to the topic of your tutorial, e.g. `r_tidy_data` or `database_query_inboveg` and not ~~`my_tutorial`~~. - Navigate to the subfolder `content/tutorials` and create a new subfolder in this directory. This will be the directory of your tutorial. Again, use a representative name for the directory name similar to the branch name. - Within the folder, create a new file markdown `index.md`. The header of this file has an agreed format and you should copy paste this to start with: @@ -128,7 +128,7 @@ Replace all the CAPITAL words with appropriate information: Underneath the last triple dahs (`---`), you can write the tutorial as you like using [markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). -- `add`/`commit` the file to git, cfr. [STEP 2 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#while_editing). You can commit the tutorial all in once or split the commits in different steps, that is up to you. To make sure your work is updated online as well, `push` the tutorial as in [STEP 3 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_3:_push_your_changes_to_github). +- `add`/`commit` the file to git, *cf.* [STEP 2 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#while_editing). You can commit the tutorial all in once or split the commits in different steps, that is up to you. To make sure your work is updated online as well, `push` the tutorial as in [STEP 3 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_3:_push_your_changes_to_github). - When ready, `push` your tutorial a last time and create a `Pull request` to the website maintainers as explained in [STEP 4 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_4:_pull_request_to_add_your_changes_to_the_current_master). After you pull request, your submission will be checked and reviewed. When accepted and merged, you tutorial will be online. @@ -141,7 +141,7 @@ If it is your first submission using your computer, [clone](https://inbo.github. Next, we use the [git workflow](https://inbo.github.io/git-course/workflow_rstudio.html) to submit the new tutorial: -- Update your code and create a new branch, cfr. [STEP 1 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#option-1a-ill-make-a-new-branch-to-work-with). Provide a useful name for your branch related to the topic of your tutorial, e.g. `r_tidy_data` or `database_query_inboveg` and not ~~`my_tutorial`~~. +- Update your code and create a new branch, *cf.* [STEP 1 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#option-1a-ill-make-a-new-branch-to-work-with). Provide a useful name for your branch related to the topic of your tutorial, e.g. `r_tidy_data` or `database_query_inboveg` and not ~~`my_tutorial`~~. - Navigate to the subfolder `content/tutorials` and create a new subfolder in this directory. This will be the directory of your tutorial. Again, use a representative name for the directory name similar to the branch name. - Within the folder, create a new file markdown `index.Rmd`. The header of this file has an agreed format and you should copy paste this to start with: @@ -180,7 +180,7 @@ As the Rmarkown file will not be part of the website, make sure to click the `kn **Notice**: always knit the Rmarkdown file before you start committing the changes! -- `add`/`commit` **both files** to git, *cfr.* [STEP 2 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#while_editing). You can commit the tutorial all in once or split the commits in different steps, that is up to you. To make sure your work is updated online as well, `push` the tutorial as in [STEP 3 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_3:_push_your_changes_to_github). +- `add`/`commit` **both files** to git, *cf.* [STEP 2 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#while_editing). You can commit the tutorial all in once or split the commits in different steps, that is up to you. To make sure your work is updated online as well, `push` the tutorial as in [STEP 3 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_3:_push_your_changes_to_github). - When ready, `push` your tutorial a last time and create a `Pull request` to the website maintainers as explained in [STEP 4 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_4:_pull_request_to_add_your_changes_to_the_current_master). After you pull request, your submission will be checked and reviewed. When accepted and merged, you tutorial will be online. From d9a9724efad0b88b5c8fc9da0750da3f46e3cba3 Mon Sep 17 00:00:00 2001 From: Falk Mielke Date: Fri, 14 Feb 2025 11:52:38 +0100 Subject: [PATCH 4/6] update_pr_template: proofread "create tutorial" --- content/create_tutorial/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/create_tutorial/index.md b/content/create_tutorial/index.md index fd4f9fa0f..91f40b5db 100644 --- a/content/create_tutorial/index.md +++ b/content/create_tutorial/index.md @@ -15,7 +15,7 @@ In this page, the roadmap towards a new tutorial will be explained. ## Writing a tutorial -Each tutorial is setup in a subfolder of the `content/tutorials` folder. Within this folder, different files and formats may exist as you create them, but a file with the name `index.md` will be used for the tutorials website. So, you can create the tutorial directly in markdown or create it based on a [Rmarkdown](https://rmarkdown.rstudio.com/), a [Jupyter notebook](https://jupyter.org/) or any other format, as long as there is a single markdown file with the name `index.md` in your tutorial folder. +Each tutorial is setup in a subfolder of the `content/tutorials` folder. Within this folder, different files and formats may exist as you create them, but a file with the name `index.md` will be used for the tutorials website. So, you can create the tutorial directly in markdown or create it based on a [Rmarkdown](https://rmarkdown.rstudio.com/), a [Jupyter notebook](https://jupyter.org/), [quarto](https://quarto.org/docs/output-formats/hugo.html) or any other format, as long as there is a single markdown file with the name `index.md` in your tutorial folder. There are different ways to create this file. We will provide in this document specific instructions for markdown an Rmarkdown based tutorials. Still, if you got useful information or text in another format or you got stuck with the description, do not hesitate to describe your submission in a [new issue ](https://github.com/inbo/tutorials/issues/new). If you do not have a Github account, ask the [IT helpdesk](mailto:ict.helpdesk@inbo.be). We will try to support you as soon as possible. @@ -94,7 +94,7 @@ Next, click `commit new file` and your submission will be reviewed by the websit When you ever used git or Github before, either using the command line, rstudio, Github Desktop,... you can work on your own computer and submit the tutorial using git. In this section, we assume you are familiar to the git command or interface and have some basic knowledge. If not, no worries, we have a dedicated course to get you up to speed, see the [INBO git course](https://inbo.github.io/git-course/). -_**Notice**: The links in the different steps will refer to the Rstudio steps in the INBO git tutorial, but can be done using other interfaces or the command line as well. Pick the one you prefer_ +_**Notice**: The links in the different steps will refer to the Rstudio steps in the INBO git tutorial, but can be done using other interfaces or the command line as well. Pick the one you prefer._ If it is your first submission using your computer, [clone](https://inbo.github.io/git-course/course_rstudio.html#23_clone_a_repo_to_work_locally) the [INBO tutorials](https://github.com/inbo/tutorials) repository (*so use the clone button on the https://github.com/inbo/tutorials page!*). From 069866692b596e2d1d9ab3157e4872dc862796a9 Mon Sep 17 00:00:00 2001 From: Falk Mielke Date: Fri, 14 Feb 2025 12:09:02 +0100 Subject: [PATCH 5/6] update_pr_template: refresh pr template --- .github/pull_request_template.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e4ccf7629..e51ebf0a0 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -24,11 +24,15 @@ for an explanation on how to use task lists--> -- [ ] My tutorial or article is placed in a subfolder of `tutorials/content` +- [ ] My tutorial or article is placed in a subfolder of `tutorials/content/` +- [ ] The novel tutorial has a meaningful name, in relation to the content of the tutorial. - [ ] 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). -- [ ] I have included `tags` in the YAML header (see the tags listed in the [tutorials website side bar](https://inbo.github.io/tutorials/) for tags that have been used before) -- [ ] I have added `categories` to the YAML header and my category tags are from the [list of category tags](https://github.com/inbo/tutorials/blob/master/static/list_of_categories) -- [ ] I have previewed this PR locally (see steps below) and confirmed that the new content renders as expected. +- `yaml` header: + - [ ] *(recommended)* I am included as author in the `authors` yaml tag, using `[MY_AUTHOR_ID]`. An author information file exists in `/data/authors/.toml`. + - [ ] I have added `categories` to the YAML header and my category tags are from the [list of category tags](https://github.com/inbo/tutorials/blob/master/static/list_of_categories) + - [ ] *(optional)* I have included `tags` in the YAML header (see the tags listed in the [tutorials website side bar](https://inbo.github.io/tutorials/) for tags that have been used before) + - [ ] The `date` is in format `YYYY-MM-DD` and adjusted. +- [ ] *(recommended)* I have previewed this PR locally (see steps below; ask previous contributors for help) and confirmed that the new content renders as expected. ## Previewing the pull request @@ -40,8 +44,14 @@ This provides a way to preview how these updates will look on the website, usefu 1) On the PR page, you can find a "details" link under "checks - On PR, build the site and ...". Go there, click on the top link in the left sidebar ("Summary"), and download the generated artifact at the bottom of the page. 2) Decompress it into a target directory, e.g. `Downloads/tutorials_preview`. -3) To preview the website, use a program which can serve `http` sites on your local machine. One such option is [the `servr` package](https://github.com/yihui/servr) in R: `& '\C:\Program Files\R\R-4.4.2\bin\Rscript.exe' -e "servr::httd('./tutorials_preview')" -p8887` +3) To preview the website, use a program which can serve `http` sites on your local machine. One such option is [the `servr` package](https://github.com/yihui/servr) in R: `& '\C:\Program Files\R\R-4.4.2\bin\Rscript.exe' -e "servr::httd('./tutorials_preview')" -p8887` (*make sure to adjust the path to your `Rscript.exe`*). 4) Point your browser to http://localhost:8887. 5) Review the updated website. As a contributor, you can push extra commits to update the PR. As a reviewer, you can accept/refuse/comment the PR. **Note: for step 3, you can use any other simple HTTP server to serve the current directory, e.g. [Python `http.server`](https://docs.python.org/3/library/http.server.html): `python -m http.server 8887 --bind localhost --directory path/to/tutorials_preview`** + + +### Alternative: Locally Building the Site + +Alternatively, you can build the entire site locally ([see the README for instructions](https://github.com/inbo/tutorials?tab=readme-ov-file#building-the-site)); the Hugo preview server will update changes on the fly. +This requires [Hugo](https://gohugo.io/getting-started) to be installed on your computer. From 5bf685649ec724ee7ff1c46e1d4eff2ce5e26e30 Mon Sep 17 00:00:00 2001 From: Falk Mielke Date: Thu, 20 Feb 2025 09:03:54 +0100 Subject: [PATCH 6/6] update_pr_template: additional suggestions* by @florisvdh, https://github.com/inbo/tutorials/pull/357 --- .github/pull_request_template.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e51ebf0a0..6087d8ec2 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -29,8 +29,8 @@ for an explanation on how to use task lists--> - [ ] 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). - `yaml` header: - [ ] *(recommended)* I am included as author in the `authors` yaml tag, using `[MY_AUTHOR_ID]`. An author information file exists in `/data/authors/.toml`. - - [ ] I have added `categories` to the YAML header and my category tags are from the [list of category tags](https://github.com/inbo/tutorials/blob/master/static/list_of_categories) - - [ ] *(optional)* I have included `tags` in the YAML header (see the tags listed in the [tutorials website side bar](https://inbo.github.io/tutorials/) for tags that have been used before) + - [ ] I have added `categories` to the YAML header and my category tags are from the [list of categories](https://github.com/inbo/tutorials/blob/master/static/list_of_categories). + - [ ] I have included meaningful and applicable `tags` (i.e. keywords) in the YAML header to improve the visibility of the new tutorial (see the tags listed in the [tutorials website side bar](https://inbo.github.io/tutorials/)). - [ ] The `date` is in format `YYYY-MM-DD` and adjusted. - [ ] *(recommended)* I have previewed this PR locally (see steps below; ask previous contributors for help) and confirmed that the new content renders as expected. @@ -44,7 +44,7 @@ This provides a way to preview how these updates will look on the website, usefu 1) On the PR page, you can find a "details" link under "checks - On PR, build the site and ...". Go there, click on the top link in the left sidebar ("Summary"), and download the generated artifact at the bottom of the page. 2) Decompress it into a target directory, e.g. `Downloads/tutorials_preview`. -3) To preview the website, use a program which can serve `http` sites on your local machine. One such option is [the `servr` package](https://github.com/yihui/servr) in R: `& '\C:\Program Files\R\R-4.4.2\bin\Rscript.exe' -e "servr::httd('./tutorials_preview')" -p8887` (*make sure to adjust the path to your `Rscript.exe`*). +3) To preview the website, use a program which can serve `http` sites on your local machine. One such option is [the `servr` package](https://github.com/yihui/servr) in R: `& '\C:\Program Files\R\R-4.4.2\bin\Rscript.exe' -e "servr::httd('./tutorials_preview')" -p8887` (*make sure to adjust the path to your `Rscript.exe`*; on Linux, simply use `Rscript -e [...]`). 4) Point your browser to http://localhost:8887. 5) Review the updated website. As a contributor, you can push extra commits to update the PR. As a reviewer, you can accept/refuse/comment the PR.