From 46741c137dfeb2254bd57e3b6b1cde9bc0e4a37b Mon Sep 17 00:00:00 2001 From: Samantha Wittke Date: Mon, 27 Jul 2026 17:37:35 +0300 Subject: [PATCH 1/7] add sphinx bioschemas --- .github/workflows/sphinx.yml | 1 + content/conf.py | 3 +++ 2 files changed, 4 insertions(+) diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 084d0d6..476f955 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -50,6 +50,7 @@ jobs: run: | python -m pip install --upgrade pip pip install -r requirements.txt + pip install sphinx-bioschemas # Debug - name: Debugging information diff --git a/content/conf.py b/content/conf.py index f13758a..bcd0e53 100644 --- a/content/conf.py +++ b/content/conf.py @@ -39,6 +39,7 @@ # remove once sphinx_rtd_theme updated for contrast and accessibility: "sphinx_rtd_theme_ext_color_contrast", "sphinx_coderefinery_branding", + "sphinx_bioschemas", ] # Settings for myst_nb: @@ -75,6 +76,8 @@ "*venv*", ] +# Add bioschemas +bioschemas = ["bioschemas.yaml"] # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output From 7200a78c3c89bed41dae91ec088feab37822fa86 Mon Sep 17 00:00:00 2001 From: Samantha Wittke Date: Mon, 27 Jul 2026 19:50:46 +0300 Subject: [PATCH 2/7] add bioschemas sphinx --- .gitignore | 1 + bioschemas.yml | 79 ++++++++++++++++++++++++++++++++++++++++++++++++ content/conf.py | 2 +- requirements.txt | 1 + 4 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 bioschemas.yml diff --git a/.gitignore b/.gitignore index 30ed516..50bf547 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ _build/ venv/ .*.sw? +*.DS_Store diff --git a/bioschemas.yml b/bioschemas.yml new file mode 100644 index 0000000..75362fd --- /dev/null +++ b/bioschemas.yml @@ -0,0 +1,79 @@ +{ + "@context": "https://schema.org/", + "@type": "LearningResource", + "@id": "https://coderefinery.github.io/documentation/", + "description": "The lesson 'How to document your research software' gives an overview of the different ways how a code project can be documented: from small projects to larger projects. Markdown and Sphinx are central tools in this lesson.", + "keywords": "Documentation, Sphinx", + "name": "How to document your research software", + #"about": "", + #"audience": "", + "author": [ + { + "@type": "Organization", + "name": "CodeRefinery" + }, + { + "@type": "Person", + "name": "Radovan Bast" + }, + { + "@type": "Person", + "name": "Richard Darst" + }, + { + "@type": "Person", + "name": "Bj\u00f8rn Lindi" + }, + { + "@type": "Person", + "name": "Stefan Negru" + }, + { + "@type": "Person", + "name": "Luisa Orozco" + }, + { + "@type": "Person", + "name": "Jarno Rantaharju" + }, + { + "@type": "Person", + "name": "Annajiat Alim Rasel" + }, + { + "@type": "Person", + "name": "Sabry Razick" + }, + { + "@type": "Person", + "name": "Sven van der Burg" + }, + { + "@type": "Person", + "name": "Marijn van Vliet" + }, + { + "@type": "Person", + "name": "Kjartan Thor Wikfeldt" + }, + { + "@type": "Person", + "name": "Samantha Wittke" + }, + { + "@type": "Person", + "name": "Michele Mesiti" + } + ], + # "competencyRequired": "", + "educationalLevel": "Beginner", + "identifier": "https://doi.org/10.5281/zenodo.8280234", + "inLanguage": "en-UK", + #"learningResourceType": "", + "license": "https://creativecommons.org/licenses/by/4.0/", + "teaches": "Understand the importance of writing code documentation together with the source code, Know what makes a good documentation, Learn what tools can be used for writing documentation, Be able to motivate a balanced decision: sometimes READMEs are absolutely enough", + "url": "https://coderefinery.github.io/documentation/", + # "accessibilitySummary": "", + "isPartOf": "CodeRefinery workshop", + "version": "2023-08-24" +} diff --git a/content/conf.py b/content/conf.py index bcd0e53..3655120 100644 --- a/content/conf.py +++ b/content/conf.py @@ -77,7 +77,7 @@ ] # Add bioschemas -bioschemas = ["bioschemas.yaml"] +bioschemas = ["bioschemas.yml"] # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/requirements.txt b/requirements.txt index c995972..739a5f5 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,3 +3,4 @@ sphinx-copybutton==0.5.2 sphinx-lesson sphinx_rtd_theme_ext_color_contrast https://github.com/coderefinery/sphinx-coderefinery-branding/archive/master.zip +sphinx-bioschemas From 7f8f4c2d22b10d37990838896ae7d9098061b706 Mon Sep 17 00:00:00 2001 From: Samantha Wittke Date: Mon, 27 Jul 2026 19:51:16 +0300 Subject: [PATCH 3/7] rearrange credit, license and citation info --- content/index.md | 3 +-- content/{license.md => reusing.md} | 31 +++++++++++++++++++++++++----- 2 files changed, 27 insertions(+), 7 deletions(-) rename content/{license.md => reusing.md} (62%) diff --git a/content/index.md b/content/index.md index 52617e5..d119597 100644 --- a/content/index.md +++ b/content/index.md @@ -90,7 +90,6 @@ gh-pages.md Shell crash course exercises.md guide.md -license.md ``` ```{toctree} @@ -99,5 +98,5 @@ license.md All lessons CodeRefinery -Reusing +reusing.md ``` diff --git a/content/license.md b/content/reusing.md similarity index 62% rename from content/license.md rename to content/reusing.md index d261f28..2d89cef 100644 --- a/content/license.md +++ b/content/reusing.md @@ -1,15 +1,16 @@ -# Credit and license +# Reusing -This material is provided by CodeRefinery under the licenses stated below. +This lesson material is free to reuse, adapt, and cite. This page collects +everything you need to do so. +## License -## Website template +### Website template The website template is maintained by [CodeRefinery](https://coderefinery.org/) and rendered with [sphinx-lesson: structured lessons with Sphinx](https://coderefinery.github.io/sphinx-lesson/). - -## Instructional material +### Instructional material All CodeRefinery instructional material is made available under the [Creative Commons Attribution license (CC-BY-4.0)](https://creativecommons.org/licenses/by/4.0/). @@ -43,3 +44,23 @@ With the understanding that: permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material. + +## How to cite this lesson + +If you use this lesson material, please cite it using the metadata below: + +> CodeRefinery community (2023). "How to document your research software" +> (Version 2023-08-24) [Data set]. Zenodo. + +The authoritative, machine-readable citation record is kept in +[`CITATION.cff`](https://raw.githubusercontent.com/coderefinery/documentation/refs/heads/main/CITATION.cff) +at the root of this lesson's repository, which lists the full set of +contributing authors and stays up to date as the lesson evolves. + +## Structured metadata + +This lesson also publishes its metadata as machine-readable +[Bioschemas](https://bioschemas.org/) / [schema.org](https://schema.org/) +structured data, embedded as JSON-LD on every page of this site. You can +inspect the source directly in +[`bioschemas.yml`](https://raw.githubusercontent.com/coderefinery/documentation/refs/heads/main/bioschemas.yml). \ No newline at end of file From 5c9d79dce750a5a93b193753c26df00f88ed1c76 Mon Sep 17 00:00:00 2001 From: Samantha Wittke Date: Mon, 27 Jul 2026 20:57:44 +0300 Subject: [PATCH 4/7] Update to more maintainable citation --- content/reusing.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/content/reusing.md b/content/reusing.md index 2d89cef..bcfbfc8 100644 --- a/content/reusing.md +++ b/content/reusing.md @@ -47,12 +47,11 @@ With the understanding that: ## How to cite this lesson -If you use this lesson material, please cite it using the metadata below: +If you use this lesson material, please cite it using this DOI: -> CodeRefinery community (2023). "How to document your research software" -> (Version 2023-08-24) [Data set]. Zenodo. + -The authoritative, machine-readable citation record is kept in +The machine-readable citation record is kept in [`CITATION.cff`](https://raw.githubusercontent.com/coderefinery/documentation/refs/heads/main/CITATION.cff) at the root of this lesson's repository, which lists the full set of contributing authors and stays up to date as the lesson evolves. From a98e0d8e50547d13a75d9601c1736dbaf5ddc4ae Mon Sep 17 00:00:00 2001 From: Samantha Wittke <32324155+samumantha@users.noreply.github.com> Date: Wed, 29 Jul 2026 19:38:41 +0300 Subject: [PATCH 5/7] remove duplicate Co-authored-by: Richard Darst --- .github/workflows/sphinx.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 476f955..084d0d6 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -50,7 +50,6 @@ jobs: run: | python -m pip install --upgrade pip pip install -r requirements.txt - pip install sphinx-bioschemas # Debug - name: Debugging information From f32b4972642484121bb9f3c06033d12fce1a9fdb Mon Sep 17 00:00:00 2001 From: Samantha Wittke Date: Thu, 30 Jul 2026 11:30:18 +0300 Subject: [PATCH 6/7] remove unused keywords for clarity --- bioschemas.yml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/bioschemas.yml b/bioschemas.yml index 75362fd..b901a54 100644 --- a/bioschemas.yml +++ b/bioschemas.yml @@ -5,8 +5,6 @@ "description": "The lesson 'How to document your research software' gives an overview of the different ways how a code project can be documented: from small projects to larger projects. Markdown and Sphinx are central tools in this lesson.", "keywords": "Documentation, Sphinx", "name": "How to document your research software", - #"about": "", - #"audience": "", "author": [ { "@type": "Organization", @@ -65,15 +63,12 @@ "name": "Michele Mesiti" } ], - # "competencyRequired": "", "educationalLevel": "Beginner", "identifier": "https://doi.org/10.5281/zenodo.8280234", "inLanguage": "en-UK", - #"learningResourceType": "", "license": "https://creativecommons.org/licenses/by/4.0/", "teaches": "Understand the importance of writing code documentation together with the source code, Know what makes a good documentation, Learn what tools can be used for writing documentation, Be able to motivate a balanced decision: sometimes READMEs are absolutely enough", "url": "https://coderefinery.github.io/documentation/", - # "accessibilitySummary": "", "isPartOf": "CodeRefinery workshop", "version": "2023-08-24" } From 582c4f5d00ca3ad04c710eb0c17a1090a71fd084 Mon Sep 17 00:00:00 2001 From: Samantha Wittke Date: Thu, 30 Jul 2026 11:38:02 +0300 Subject: [PATCH 7/7] move important things first --- content/reusing.md | 37 +++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/content/reusing.md b/content/reusing.md index bcfbfc8..9dd56f1 100644 --- a/content/reusing.md +++ b/content/reusing.md @@ -3,6 +3,25 @@ This lesson material is free to reuse, adapt, and cite. This page collects everything you need to do so. +## How to cite this lesson + +If you use this lesson material, please cite it using this DOI: + + + +The machine-readable citation record is kept in +[`CITATION.cff`](https://raw.githubusercontent.com/coderefinery/documentation/refs/heads/main/CITATION.cff) +at the root of this lesson's repository, which lists the full set of +contributing authors and stays up to date as the lesson evolves. + +## Structured metadata + +This lesson also publishes its metadata as machine-readable +[Bioschemas](https://bioschemas.org/) / [schema.org](https://schema.org/) +structured data, embedded as JSON-LD on every page of this site. You can +inspect the source directly in +[`bioschemas.yml`](https://raw.githubusercontent.com/coderefinery/documentation/refs/heads/main/bioschemas.yml). + ## License ### Website template @@ -45,21 +64,3 @@ With the understanding that: rights such as publicity, privacy, or moral rights may limit how you use the material. -## How to cite this lesson - -If you use this lesson material, please cite it using this DOI: - - - -The machine-readable citation record is kept in -[`CITATION.cff`](https://raw.githubusercontent.com/coderefinery/documentation/refs/heads/main/CITATION.cff) -at the root of this lesson's repository, which lists the full set of -contributing authors and stays up to date as the lesson evolves. - -## Structured metadata - -This lesson also publishes its metadata as machine-readable -[Bioschemas](https://bioschemas.org/) / [schema.org](https://schema.org/) -structured data, embedded as JSON-LD on every page of this site. You can -inspect the source directly in -[`bioschemas.yml`](https://raw.githubusercontent.com/coderefinery/documentation/refs/heads/main/bioschemas.yml). \ No newline at end of file