PRJ: How to reference Lectures?

[mmcky]

Can we integrate DOI into the QuantEcon lectures?

Is there a way to give each lecture its own DOI?

This is feedback from @HumphreyYang and @jstac

[mmcky]

DOI Integration for QuantEcon Lectures

Overview

This document outlines the options and requirements for integrating DOIs to enable citation of QuantEcon lectures hosted on sites like https://python.quantecon.org.

Recommended Approach: Zenodo + GitHub Integration

The most straightforward approach is to use the Zenodo-GitHub integration, which automatically archives releases and mints DOIs.

Setup Steps

1. Connect GitHub to Zenodo

   • Log into Zenodo using your GitHub account
   • Navigate to Settings → GitHub and authorise the integration

2. Enable the repository

   • Toggle on the lecture repository (e.g., QuantEcon/lecture-python-intro) in Zenodo's GitHub settings

3. Add a CITATION.cff file to the repository root (see template below)

4. Create a GitHub release

   • When a release is published, Zenodo automatically archives it and mints a DOI

5. Add DOI badge to README and website

Benefits

• GitHub displays a "Cite this repository" button in the sidebar automatically
• Zenodo provides both a concept DOI (always points to latest version) and version-specific DOIs
• Automatic archiving with each release
• No ongoing maintenance required

CITATION.cff Template

cff-version: 1.2.0
message: "If you use these lectures, please cite them as below."
title: "QuantEcon Python Lectures"
abstract: "A series of lectures on quantitative economics using Python"
authors:
  - family-names: Stachurski
    given-names: John
    orcid: "https://orcid.org/XXXX-XXXX-XXXX-XXXX"
  - family-names: Sargent
    given-names: Thomas J.
    orcid: "https://orcid.org/XXXX-XXXX-XXXX-XXXX"
version: "2024.1"
date-released: "2024-01-15"
license: BSD-3-Clause
repository-code: "https://github.com/QuantEcon/lecture-python-intro"
url: "https://python.quantecon.org"
keywords:
  - economics
  - python
  - computational economics
  - quantitative economics

Note: Update author ORCIDs, version, date, and other metadata as appropriate.

Website Integration

MyST Markdown DOI Support

Jupyter Book / MyST Markdown has built-in DOI citation support. Link to any DOI and it will render as a citation with hover preview:

[Stachurski & Sargent, 2024](https://doi.org/10.5281/zenodo.XXXXXXX)

"How to Cite" Page

Consider adding a dedicated citation page or sidebar section to the website that displays:

• The recommended citation in multiple formats (APA, BibTeX)
• The DOI badge linking to Zenodo
• Version information

Alternative: Per-Lecture DOIs

If individual lectures need to be independently citable:

• Upload each lecture separately to Zenodo (manual process)
• Use a platform like Figshare that supports finer-grained DOI assignment

This adds complexity and maintenance overhead, so repository-level DOIs are recommended as a starting point.

Resources

• Zenodo GitHub Integration Guide
• CITATION.cff Format Documentation
• CFF Initializer Tool
• GitHub Citation Files Documentation
• MyST Markdown Citations

Tasks

• Create Zenodo account (if not existing) and connect to GitHub
• Enable relevant lecture repositories in Zenodo
• Draft CITATION.cff files for each repository
• Add "How to Cite" section to lecture websites
• Create initial GitHub release to trigger first DOI
• Add DOI badges to README files

[mmcky]

We want to explore lectures level referencing and DOIs as lectures can change between lecture series.