search

DanNBullock / citeas-on-requirements

GitHub action for using the CiteAs API to generate a software citation ACKNOWLEDGEMENTS.md document from requirements.txt
Apache License 2.0
1 stars 0 forks source link
academic-publishing automated-documentation automatic-documentation citation citeas github-actions

readme

CiteAs-on-requirements

(A proof-of-concept / test of Cunningham's Law)

Overview

GitHub action for using the CiteAs API to generate a software citation ACKNOWLEDGEMENTS.md document automatically from a requirements.txt file.

See usage note below for issues relating to citation output quality

Keywords

keywords: citation, automatic-documentation, automated-documentation, github-actions, citeas

Usage

Example Workflow

name: Citation update
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@master
      - name: Self test
        id: generateCitation
        description: "GitHub action which builds citations from requirements.txt"
        uses: DanNBullock/citeas-on-requirements@master

        # The input requirements.txt file (as a string?)
        with:
          inputFile: "requirements.txt"
          # [0 = 'APS', 1 = 'Harvard', 2 = 'Nature', 3 = 'MLA', 4 = 'Chicago', 5 = 'Vancouver']
          formatSelect: 2
      - name: Commit changes
        uses: test-room-7/action-update-file@v1
        description: "GitHub action to commit the specific updated file"
        with:
          file-path: 'ACKNOWLEDGMENTS.md'
          commit-msg: Update ACKNOWLEDGMENTS.md
          github-token: ${{ secrets.GITHUB_TOKEN }}

Inputs

Input Description Default
inputFile Path to the requirements.txt file "requirements.txt"
formatSelect Index to select the output format of citations : [0: 'APS', 1: 'Harvard', 2: 'Nature', 3: 'MLA', 4: 'Chicago', 5: 'Vancouver'] 2

IMPORTANT USAGE NOTE

In essence, this GitHub action is just a wrapper around the CiteAs API. While CiteAs is a great resource, it is not perfect. In particular, it currently appears to have some trouble with prompts that are based upon simply the package name (as would be the case for information coming from the requirements.txt file)--CiteAs functionality with DOIs or repository URLs seems to work more reliabily. It is hoped that as CiteAs develops and becomes more robust, so too will the output of this resource.

Recomendations on obtaining a requirements.txt file

The operation of this GitHub action is predicated upon the assumption that an accepted "manifest-type" file (e.g. requirements.txt, Dockerfile, pyproject.toml) is present in the repository--although currently only requirements.txt is accepted. A requirements.txt file can be generated manually or, using pipreqs or other such methods, automatically. There is even an existing GitHub action for automatically generating a requirements.txt, pipreqs-action, which can do this as well. However, it's worth noting that for this GitHub action implementation, the versioning information that is transcribed to the output requirements.txt is not coming from your local environment / setup. In any case, for the purposes of this GitHub action (and citation more generally), having a poorly versioned requirements.txt is better than not having one at all.

Project / Codebase overview

Project / codebase provenance

Rationale

This project is hoped to help adress an apparent gap in the open-source and scientific-software landscape. Namely, the lack of an automated method for generating software citations within and/or for scientific software packages. The consequences of this shortcoming have been discussed at length elsewhere (see Citations for some of these publications). With the provison of this capability (or at least this proof of concept), it is hoped that the hurdles to the production of software bibliographies--which would otherwise have to be produced manually--are reduced.

Support elements

Authors

Contributors

[Be the first!]

Development elements

License

Apache License 2.0

Support

[todo]

Contributing

Contributions are welcome and encouraged, particularly in the following areas:

Roadmap

Here are some capabilites that are hoped to be added soon:

Citations

Software

(Ironically, made via zbib.org)

Publications