Merge pull request #270 from coderefinery/citation

Make lesson citable

Author: bast

.github/workflows/sphinx.yml

@@ -58,6 +58,11 @@ jobs:
         run: |
           make dirhtml
 
+      - name: Generate PDF
+        run: |
+          pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip
+          make pyppeteer
+          mv _build/pyppeteer/*.pdf _build/dirhtml/_static/lesson.pdf
 
       # The following supports building all branches and combining on
       # gh-pages

.github/workflows/validate-cff.yml

@@ -0,0 +1,20 @@
+on:
+  push:
+    paths:
+      - CITATION.cff
+  workflow_dispatch:
+
+name: CITATION.cff
+jobs:
+  Validate-CITATION-cff:
+    runs-on: ubuntu-latest
+    name: Validate CITATION.cff
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Validate CITATION.cff
+        uses: dieghernan/cff-validator@main

README.md

@@ -1,4 +1,4 @@
-# Code documentation lesson
+# How to document your research software
 
 - [Credit and license](https://coderefinery.github.io/documentation/license/)
 - [How to preview the lesson locally](https://coderefinery.github.io/sphinx-lesson/contributing-to-a-lesson/#build-and-test-locally)

citation.cff

@@ -0,0 +1,36 @@
+cff-version: 1.2.0
+message: "If you use this lesson material, please cite it using these metadata."
+authors:
+- name: "CodeRefinery"
+- family-names: "Bast"
+  given-names: "Radovan"
+- family-names: "Wikfeldt"
+  given-names: "Kjartan Thor"
+- family-names: "Rantaharju"
+  given-names: "Jarno"
+- family-names: "Darst"
+  given-names: "Richard"
+- family-names: "Wittke"
+  given-names: "Samantha"
+- family-names: "van der Burg"
+  given-names: "Sven"
+- family-names: "Razick"
+  given-names: "Sabry"
+- family-names: "Rasel"
+  given-names: "Annajiat Alim"
+- family-names: "Negru"
+  given-names: "Stefan"
+- family-names: "Lindi"
+  given-names: "Bjørn"
+- family-names: "van Vliet"
+  given-names: "Marijn"
+- family-names: "Orozco"
+  given-names: "Luisa"
+title: "How to document your research software"
+type: "data"
+abstract: "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."
+version: 2023-08-10
+date-released: 2023-08-10
+url: "https://coderefinery.github.io/documentation/"
+license: CC-BY-4.0
+repository-code: "https://github.com/coderefinery/documentation"

content/conf.py

@@ -17,8 +17,8 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "Code documentation"
-copyright = "2021, CodeRefinery team"
+project = "How to document your research software"
+copyright = "CodeRefinery team"
 author = "CodeRefinery team"
 github_user = "coderefinery"
 github_repo_name = "documentation"  # auto-detected from dirname if blank
@@ -41,10 +41,7 @@
 
 # Settings for myst_nb:
 # https://myst-nb.readthedocs.io/en/latest/use/execute.html#triggering-notebook-execution
-# jupyter_execute_notebooks = "off"
-# jupyter_execute_notebooks = "auto"   # *only* execute if at least one output is missing.
-# jupyter_execute_notebooks = "force"
-jupyter_execute_notebooks = "cache"
+nb_execution_mode = "cache"
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']

content/guide.md

@@ -47,7 +47,7 @@ of time.
 ### Detailed schedule
 
 ```markdown
-* 10:45 - 12:30 Documentation
+* 10:45 - 12:30 How to document your research software
     - 10:45 - 10:55 Motivation and tools
         - create a wishlist in HackMD
     - 10:55 - 11:05 Break

content/index.rst

@@ -1,5 +1,5 @@
-Code documentation
-==================
+How to document your research software
+======================================
 
 In this lesson we will discuss different solutions for implementing and
 deploying code documentation.