From 57933f6c1cec979a38f4997f758208bcabcf40b6 Mon Sep 17 00:00:00 2001 From: Elizabeth Campolongo <38985481+egrace479@users.noreply.github.com> Date: Wed, 29 Apr 2026 13:38:27 -0400 Subject: [PATCH] Revise Citation section of GH repo guide Pull from Collab Guide [PR 69](https://github.com/Imageomics/Collaborative-distributed-science-guide/pull/69) * Restructure citation template section for improved clarity set up a standard vs extended citation also adds references as a key in Zenodo metadata template, with citation pointer recommending use there * Add support for content tabs used for citation CFF templates * Use conference-paper as default for preferred-citation include examples and exlanations for keys * fix formatting for citation file examples * Shorten note before template citation files Move preferred-citation notes to tab where it's included * Replace note about yaml validator tool with note to check format on branch validator tool checks yaml, not citation cff format * Create a subsubsection for citation templates, reduce admonition use to avoid clutter * Fix formatting of ORCID field * Clarify use of ORCID number only for zenodo JSON, different from CFF field * Add comment about when to update commit hash --- docs/wiki-guide/GitHub-Repo-Guide.md | 164 ++++++++++++++++++--------- mkdocs.yaml | 2 + 2 files changed, 112 insertions(+), 54 deletions(-) diff --git a/docs/wiki-guide/GitHub-Repo-Guide.md b/docs/wiki-guide/GitHub-Repo-Guide.md index 0655311..d516a3f 100644 --- a/docs/wiki-guide/GitHub-Repo-Guide.md +++ b/docs/wiki-guide/GitHub-Repo-Guide.md @@ -101,66 +101,119 @@ For more information on managing these environments and generating such files pr ### CITATION -Make it easier for people to cite your project by including a [CITATION.cff file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files); you can copy-paste the template below. +Make it easier for people to cite your project by including a [CITATION.cff file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files); you can copy-paste the [template below](#citation-templates). As with journal publications, we expect to be cited when someone uses our code. To facilitate proper attribution, GitHub will automatically read a [CITATION.cff file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) and display a link to "cite this repository". This file is also used to populate metadata fields in a [Zenodo](https://zenodo.org/) record when [auto-generating a DOI](DOI-Generation.md#2-generate-a-doi-with-zenodo). As with any other component of your project, this file may change over the project's lifespan (see [Digital Product Life Cycle](Digital-Product-Lifecycle.md) for details), but it should be present and updated before any release. Providing this file is as simple as copying the below example and filling in your information before uploading it to your repo. More examples and information about the Citation File Format can be found on the [citation-file-format repo](https://github.com/citation-file-format/citation-file-format), including helpful [related tools](https://github.com/citation-file-format/citation-file-format#tools-to-work-with-citationcff-files-wrench). -You can check your `CITATION.cff` file prior to upload using this [validator tool](https://www.yamllint.com/). +#### Citation Templates -!!! note "Note" - - When adding a DOI to your citation (`doi`), be sure to use the version-agnostic DOI from Zenodo. Since the DOI is not generated until _after_ the release, this ensures there will never be an "incorrect" DOI associated to the release—correct version reference is ensured through the `version` key, which should always be updated _**before**_ generating a new release. - - Subcategories of `preferred-citation` do not get bullet points, but the first subcategory of `references` must be bulleted (as below). - - This is generally intended as a reference for your code. Preferred citation can be used for the paper, though it is better to ask in the `README` that someone cites _both_ and provide the paper reference there (only the `preferred-citation` will show up to be copied from the citation box if it is included). - -```yaml { py linenums="1" } -abstract: "" -authors: -- family-names: - given-names: "" - orcid: "https://orcid.org/" -cff-version: 1.2.0 -date-released: "YYYY-MM-DD" -identifiers: - - description: "The GitHub release URL of tag ." - type: url - value: "https://github.com/Imageomics//releases/tag/" - - description: "The GitHub URL of the commit tagged with ." - type: url - value: "https://github.com/Imageomics//tree/" -keywords: - - imageomics -license: -message: "If you find this software helpful in your research, please cite both the software and our paper." -repository-code: "https://github.com/Imageomics/" -title: "" -version: -doi: # version agnostic DOI -type: software -preferred-citation: - type: article - authors: +- When adding a DOI to your citation (`doi`), be sure to use the version-agnostic DOI from Zenodo. Since the DOI is not generated until _after_ the release, this ensures there will never be an "incorrect" DOI associated to the release—correct version reference is ensured through the `version` key, which should always be updated _**before**_ generating a new release. +- A `CITATION.cff` is intended as a reference for your code; ask in the `README` that someone cites _both_ the repo and your paper, then provide the paper BibTeX there. +- Formatted display can be checked on a branch before merging to `main`. + +=== "Standard Citation File (Recommended)" + + !!! tip + Pair this citation file with a [`.zenodo.json`](#zenodo-metadata) for easier DOI metadata tracking (grants, references, associated papers). + + ```yaml { py linenums="1" } + abstract: "" + authors: - family-names: - given-names: + given-names: "" + orcid: "https://orcid.org/" + cff-version: 1.2.0 + date-released: "YYYY-MM-DD" + identifiers: + - description: "The GitHub release URL of tag ." + type: url + value: "https://github.com/Imageomics//releases/tag/" + - description: "The GitHub URL of the commit tagged with ." + type: url + value: "https://github.com/Imageomics//tree/" # Update on release + keywords: + - imageomics + license: + message: "If you find this software helpful in your research, please cite both the software and our paper." + repository-code: "https://github.com/Imageomics/" + title: "" + version: + #doi: + type: software + ``` + +=== "Extended `CFF` (References and Citation redirect)" + + !!! warning + This is generally intended as a **reference for your code**. Preferred citation can be used for the paper, though it is better to ask in the `README` that someone cites _both_ and provide the paper reference there (only the `preferred-citation` will show up to be copied from the citation box if it is included). + + !!! success "Simplify version tracking for you code" + Pair the [standard citation file](#__tabbed_1_1) with a [.zenodo.json file](#zenodo-metadata), which can track references, associated papers, and grant information. + + !!! info + - Subcategories of `preferred-citation` do not get bullet points, but the first subcategory of `references` must be bulleted (as below). + - If including `references` or setting a `preferred-citation`, see this [bibtex to cff crosswalk](https://docs.ropensci.org/cffr/articles/bibtex-cff.html#fieldskey-crosswalk) for help in translating a BibTeX citation to the proper `CFF` format. + + ```yaml { py linenums="1" } + abstract: "" + authors: - family-names: - given-names: - title: - year: - journal: - doi: -references: - - authors: - - family-names: - given-names: - - family-names: - given-names: - title: - version: - type: - doi: - date-released: -``` + given-names: "" + orcid: "https://orcid.org/" + cff-version: 1.2.0 + date-released: "YYYY-MM-DD" + identifiers: + - description: "The GitHub release URL of tag ." + type: url + value: "https://github.com/Imageomics//releases/tag/" + - description: "The GitHub URL of the commit tagged with ." + type: url + value: "https://github.com/Imageomics//tree/" # Update on release + keywords: + - imageomics + license: + message: "If you find this software helpful in your research, please cite both the software and our paper." + repository-code: "https://github.com/Imageomics/" + title: "" + version: + #doi: + type: software + # Only include the following if you want to present the paper citation instead of code on sidebar, + # Better to include paper citation in README + preferred-citation: + type: conference-paper + authors: + - family-names: + given-names: + - family-names: + given-names: + collection-title: # "Proceedings of the ..." + collection-type: proceedings + conference: + name: # Name of conference, e.g., "ICLR 2025" + pages: #"-" + start: # First page, int + end: # Last page, int + title: # Paper title + year: + doi: + # url: use only if DOI not available + # References can be added here, but will only be read from the .zenodo.json file + # Below example set to reference code repo, `preferred-citation` types apply + references: + - authors: + - family-names: + given-names: + - family-names: + given-names: + title: + version: + type: + doi: + date-released: + ``` ## Recommended Files @@ -186,7 +239,7 @@ A `.zenodo.json` can be created by applying [cffconvert](https://github.com/cita "creators": [ { "name": "family-names, given-names", - "orcid": "", + "orcid": "", // Just the ORCID number, not the URL "affiliation": "" }, { @@ -207,7 +260,10 @@ A `.zenodo.json` can be created by applying [cffconvert](https://github.com/cita { "id": "021nxhr62::2118240" // Imageomics (::) } - ] + ], + "references": [ + // list of references as strings in APA or similar format + ] } ``` diff --git a/mkdocs.yaml b/mkdocs.yaml index 2c39936..30259d5 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -83,6 +83,8 @@ markdown_extensions: - pymdownx.inlinehilite - pymdownx.snippets - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true - pymdownx.tasklist - pymdownx.tilde - pymdownx.keys