⚠️ JOSS does not uses Whedon anymore. Whedon has been deprecated in favor of Buffy ⚠️

What is Whedon?

Whedon is a collection of command-line utilities to manage JOSS submissions. Whedon is used by the Whedon-API bot to interact with authors and reviewers during the review process on https://github.com/openjournals/joss-reviews

Setup

Whedon uses dotenv to manage local configuration. Take a look at .env-example (which needs renaming to .env to be picked up).

Whedon requires a local installation of Pandoc 2 and Pandoc-Citeproc as well as a LaTeX (ideally TeXLive) installation. See Pandoc's install instruction for details.

Is it green?

Hopefully...

Installation

Depending on how Ruby is installed on your system there might slightly different steps be necessary. Note that Whedon is only tested for reasonably modern versions of Ruby (i.e. > 2.1) Bundler is used to install dependencies.

On macOS and with a Homebrew installed Ruby Bundler should be installable with

gem install bundler

On other Linux distros this might be a separate package or already installed.

After cloning the whedon repository with

git clone https://github.com/openjournals/whedon.git

from within the whedon directory run the following command:

bundle install

or

bundle install --path vendor/bundle

Next, it's necessary to create a .env file based on the example .env.test.

The GH_TOKEN can be created following the instructions from GitHub's help pages.

Once you have edited the .env file you can run the commands described below. It might be necessary to prefix the whedon command with bundle exec or give the full path to the executable, e.g. ./bin/whedon.

Usage

There are two main ways to use Whedon, 1) via the command-line utility or 2) using the Ruby API. If you want to see how the command line is implemented, take a look at the executable.

Currently implemented functionality

List available commands:

$ bundle exec whedon # or just 'whedon' depending on whether you have built and installed the RubyGem locally

Commands:
  whedon compile         # Compile the paper and XML metadata
  whedon deposit         # Deposit the metadata with the JOSS application and Crossref
  whedon download        # Download the repo
  whedon help [COMMAND]  # Describe available commands or one specific command
  whedon open            # Open browser for review
  whedon prepare         # Just prepare the PDF
  whedon reviews         # Lists open reviews
  whedon verify          # Check the key values in the review issue

whedon reviews

List all open reviews in the GitHub review repository:

$ whedon reviews

# Ruby API equivalent
>> require 'whedon'
>> Whedon::Paper.list

whedon verify

Verify the review issue body has key fields present:

$ whedon verify {id}

# Ruby API equivalent
>> require 'whedon'
>> Whedon::Paper.new(issue_id).audit

whedon open

Open the browser at the review issue page

$ whedon open {id}

whedon download

Download locally the repository linked to in the review issue (note this tries to do a simple git clone of the repository address which will fail for non-git repositories).

$ whedon download {id}

# Ruby API equivalent
>> require 'whedon'
>> Whedon::Paper.new(issue_id).download

whedon prepare

Compile a downloaded paper locally to a PDF.

This is the command that the Whedon-API bot uses to generate a preview of the paper PDF for sharing with reviewers and editors.

$ whedon prepare {id}

# Ruby API equivalent
>> require 'whedon'
>> review = Whedon::Review.new(issue_id)
>> processor = Whedon::Processor.new(issue_id, review.issue_body)
>> processor.set_paper(path_to_paper.md_file)
>> processor.generate_pdf

Under the hood, the prepare method does the following:

• Looks for the paper.md
  • If more than one paper.md is found, asks the user to pick the correct one
• Compiles the markdown to a custom PDF: pandoc -o paper.pdf -V geometry:margin=1in --filter pandoc-citeproc paper.md --template latex.template. See the actual command here.
• Returns the filesystem location of the compiled PDF for inspection

whedon compile

$ whedon compile {id}

# Ruby API equivalent
>> require 'whedon'
>> review = Whedon::Review.new(issue_id)
>> processor = Whedon::Processor.new(issue_id, review.issue_body)
>> processor.set_paper(path_to_paper.md_file)
>> processor.compile

Under the hood, the compile method does the following:

• Looks for the paper.md
  • If more than one paper.md is found, asks the user to pick the correct one
• Compiles the markdown to four different outputs:
  • The JOSS PDF
  • A (currently un-used) custom XML output
  • An HTML representation of the paper (deprecated)
  • The Crossref deposit metadata
• Returns the filesystem location of the compiled PDF for inspection

Functionality under development

Accept a paper into JOSS. This method currently returns the necessary metadata for the JOSS application (i.e. fields that need updating in the JOSS database) once a paper is accepted.

In the future, this method should:

• Update the database fields automatically on the JOSS application.
• Deposit the Crossref XML to the Crossref API

$ whedon deposit {id}

# Ruby API equivalent
>> require 'whedon'
>> review = Whedon::Review.new(issue_id)
>> processor = Whedon::Processor.new(issue_id, review.issue_body)
>> processor.set_paper(path_to_paper.md_file)
>> processor.deposit