Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

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


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?


Build Status


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

from within the whedon directory run the following command:

bundle install


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.


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

  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 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 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 =
>> processor =, 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
    • If more than one 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 --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 =
>> processor =, review.issue_body)
>> processor.set_paper(path_to_paper.md_file)
>> processor.compile

Under the hood, the compile method does the following:

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 =
>> processor =, review.issue_body)
>> processor.set_paper(path_to_paper.md_file)
>> processor.deposit


Command-line utilities to manage JOSS submissions. May one day be a sentient being.







No releases published


No packages published