Merge pull request #3385 from jspsych/add-citation-module

Generate citation strings from citation.cff file as part of build process

.changeset/violet-tools-appear.md

@@ -0,0 +1,62 @@
+---
+"@jspsych/plugin-serial-reaction-time-mouse": minor
+"@jspsych/plugin-canvas-keyboard-response": minor
+"@jspsych/plugin-audio-keyboard-response": minor
+"@jspsych/plugin-image-keyboard-response": minor
+"@jspsych/plugin-video-keyboard-response": minor
+"@jspsych/plugin-canvas-button-response": minor
+"@jspsych/plugin-canvas-slider-response": minor
+"@jspsych/plugin-html-keyboard-response": minor
+"@jspsych/plugin-audio-button-response": minor
+"@jspsych/plugin-audio-slider-response": minor
+"@jspsych/plugin-image-button-response": minor
+"@jspsych/plugin-image-slider-response": minor
+"@jspsych/plugin-initialize-microphone": minor
+"@jspsych/plugin-video-button-response": minor
+"@jspsych/plugin-video-slider-response": minor
+"@jspsych/plugin-categorize-animation": minor
+"@jspsych/plugin-html-button-response": minor
+"@jspsych/plugin-html-slider-response": minor
+"@jspsych/plugin-same-different-image": minor
+"@jspsych/plugin-serial-reaction-time": minor
+"@jspsych/plugin-visual-search-circle": minor
+"@jspsych/plugin-webgazer-init-camera": minor
+"@jspsych/plugin-html-audio-response": minor
+"@jspsych/plugin-html-video-response": minor
+"@jspsych/plugin-same-different-html": minor
+"@jspsych/plugin-survey-multi-choice": minor
+"@jspsych/plugin-survey-multi-select": minor
+"@jspsych/plugin-webgazer-calibrate": minor
+"@jspsych/extension-mouse-tracking": minor
+"@jspsych/plugin-initialize-camera": minor
+"@jspsych/plugin-webgazer-validate": minor
+"@jspsych/plugin-categorize-image": minor
+"@jspsych/plugin-survey-html-form": minor
+"@jspsych/plugin-virtual-chinrest": minor
+"@jspsych/extension-record-video": minor
+"@jspsych/plugin-categorize-html": minor
+"@jspsych/plugin-reconstruction": minor
+"@jspsych/plugin-browser-check": minor
+"@jspsych/plugin-call-function": minor
+"@jspsych/plugin-external-html": minor
+"@jspsych/plugin-mirror-camera": minor
+"@jspsych/plugin-survey-likert": minor
+"@jspsych/plugin-instructions": minor
+"@jspsych/extension-webgazer": minor
+"@jspsych/plugin-survey-text": minor
+"@jspsych/plugin-fullscreen": minor
+"@jspsych/plugin-animation": minor
+"@jspsych/plugin-free-sort": minor
+"@jspsych/plugin-iat-image": minor
+"@jspsych/plugin-sketchpad": minor
+"@jspsych/plugin-iat-html": minor
+"@jspsych/plugin-maxdiff": minor
+"@jspsych/plugin-preload": minor
+"@jspsych/plugin-resize": minor
+"@jspsych/plugin-survey": minor
+"@jspsych/plugin-cloze": minor
+"jspsych": minor
+"@jspsych/config": minor
+---
+
+Added citations property to info field of all plugins/extensions in two citation formats (apa, bibtex); added getCitations() as function in jsPsych package allowing user to generate citations by passing an array of plugins/extensions by name as first input and citation format as string as second input; changed template of plugins/extensions to contain citations field by default; citations for each plugin/extension are automatically generated from .cff file (if any) at its folder's root during build process; getCitations() prints out citations in the form of a string separating each citation with newline character, and always prints the jsPsych library citation first.

.gitignore

@@ -11,3 +11,4 @@ coverage/
 dist.zip
 packages/jspsych/README.md
 .turbo
+.env

docs/about/about.md

@@ -8,10 +8,20 @@ jsPsych was created by [Josh de Leeuw](https://www.vassar.edu/faculty/jdeleeuw).
 
 If you use this library in academic work, the preferred citation is:
 
-de Leeuw, J.R., Gilbert, R.A., & Luchterhandt, B. (2023). jsPsych: Enabling an open-source collaborative ecosystem of behavioral experiments. *Journal of Open Source Software*, *8*(85), 5351, [https://joss.theoj.org/papers/10.21105/joss.05351](https://joss.theoj.org/papers/10.21105/joss.05351).
+> de Leeuw, J.R., Gilbert, R.A., & Luchterhandt, B. (2023). jsPsych: Enabling an open-source collaborative ecosystem of behavioral experiments. *Journal of Open Source Software*, *8*(85), 5351, [https://joss.theoj.org/papers/10.21105/joss.05351](https://joss.theoj.org/papers/10.21105/joss.05351).
 
 This paper is an updated description of jsPsych and includes all current core team members. It replaces the earlier paper that described jsPsych:
 
-de Leeuw, J.R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a Web browser. *Behavior Research Methods*, _47_(1), 1-12. doi:[10.3758/s13428-014-0458-y](http://link.springer.com/article/10.3758%2Fs13428-014-0458-y)
+> de Leeuw, J.R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a Web browser. *Behavior Research Methods*, _47_(1), 1-12. doi:[10.3758/s13428-014-0458-y](http://link.springer.com/article/10.3758%2Fs13428-014-0458-y)
 
 Citations help us demonstrate that this library is used and valued, which allows us to continue working on it.
+
+#### Citation tool for third-party plugins/extensions
+
+jsPsych is an open-source, collaborative ecosystem, and many of the plugins/extensions you end up using may be contributed by third-party developers! We want to make sure they get recognition for their good work, so we  made a command-line citation tool that you should use to cite this library and the plugins/extensions used in your experiment. You can see this tool in action by following these steps:
+
+1. Launch a jsPsych experiment in your browser
+2. Open up the browser console using Ctrl + ⇧ + J (Windows) or ⌘ + ⌥ + J (Mac)
+3. Type `jsPsych.getCitations()`
+
+This should print the APA format citation for the jsPsych library, which you can then copy and paste into your working document. To cite the plugins/extensions in your experiment, you should pass in an array containing the name of each plugin/extension to generate a list of citations, e.g. `jsPsych.getCitations([jsPsychHtmlKeyboardResponse, jsPsychMouseTrackingExtension])`. You can also pass in the desired output citation format as the second argument, e.g. `jsPsych.getCitations([jsPsychHtmlKeyboardResponse, jsPsychMouseTrackingExtension], "apa")`. We currently support APA formatting (`"apa"`) and BibTex formatting (`"bibtex"`).

docs/developers/contributing.md

@@ -20,6 +20,8 @@ We welcome contributions of any scope. Before we can merge changes into the main
 
 * **An example file should be included if applicable.** If you are contributing a new feature, new plugin, or new extension, or contributing a modification that changes the behavior of the library in some important way, consider adding an example file to the `/examples` folder in the repository.
 
+* **If you are contributing a plugin/extension, we strongly encourage including a file containing citation information.** This file should be named `CITATION.cff` and placed at the root of your repository. This allows people who use your plugin/extension in their code to easily cite your work by calling `jsPsych.getCitations([<yourPlugin>])` from their command line. More information on `.cff` files can be found [here](https://citation-file-format.github.io/).
+
 * **A changeset must be included in the pull request**. We use [changesets](https://github.com/atlassian/changesets/blob/main/docs/adding-a-changeset.md) to generate new releases and their corresponding release notes. [This is a good overview of changesets](https://github.com/atlassian/changesets/blob/main/docs/adding-a-changeset.md) that explains how to add one to your pull request. Feel free to ask for help with this!
 
 * **Update the contributors.md file**. If you are a first time contributor to jsPsych please add your name to our [contributors file](https://github.com/jspsych/jsPsych/blob/main/contributors.md). And thanks!

docs/reference/jspsych.md

@@ -346,6 +346,34 @@ This method tells jsPsych that the current trial is over. It is used in all of t
 jsPsych.finishTrial({correct_response: true});
 ```
 
+---
+## jsPsych.getCitations
+
+```javascript
+jsPsych.getCitations(plugins, format)
+```
+### Parameters
+| Parameter | Type   | Description                                          |
+| --------- | ------ | ---------------------------------------------------- |
+| plugins   | array  | Array containing list of plugins/extensions by name. |
+| format    | string | Output citation format ("apa" | "bibtex")            |
+
+### Return value
+
+String of generated citations in the specified format for the jsPsych library, followed by that for each input plugin/extension, separated with a "\n" character.
+
+### Description
+
+Get citations in a specified format for the jsPsych library and input list of plugins/extensions, usually those used within an experiment.
+
+### Example
+
+```javascript
+// in browser console
+jsPsych.getCitations() // prints citation for jsPsych library in APA format
+jsPsych.getCitations([TestPlugin], "bibtex") // prints citation for jsPsych library and TestPlugin (if different) in BibTex format
+```
+
 ---
 ## jsPsych.getCurrentTrial