Table Of Contents

Previous topic

Diagnostic

Next topic

Web Services

This Page

Building Javadoc

Package-specific Javadoc

Dependency note

Note that package-specific Javadoc generation only works if you have successfully built the package first. If you haven’t built it before, you’re likely to get error messages about missing files.

Building

To generate Javadoc at a package-specific level, change directory to the webapp directory of a given mine, and run ant javadoc. Assuming you’re at the root of your intermine directory:

$ cd flymine/webapp
$ ant javadoc

Upon successful build, you’ll be able to find the Javadoc under the build/javadoc folder. For the FlyMine example above, it’d be at git/intermine/flymine/webapp/build/javadoc.

Generating Intermine-wide Javadoc

If you just want to browse the docs, you can see the most recent version at http://intermine.org/intermine/. If you’d like to generate it yourself, read on.

Dependencies

The Javadoc depends on the database model under bio/testall being built first. To do this, from the intermine root directory:

$ cd bio/test-all/dbmodel
$ ant clean-all
$ ant build-db

Building

Once you’ve successfully run build-db above, you’ll need to change to the imbuild/javadoc directory and generate the documentation:

$ cd ../../../imbuild/javadoc
$ ant clean
$ ant

That’s it! You’ll be able to see the documentation under intermine/imbuild/javadoc/build/javadoc.

Using Travis to auto-deploy Javadoc to GitHub Pages

If you have your InterMine repo set up to automatically run tests using Travis, you can deploy the documentation automatically whenever new code is checked into your master branch, using Github Pages as a host.

Prerequisites

In order to deploy, there must be an encrypted $GH_TOKEN set in .travis.yml to authenticate with Github. This is safe because of the way Travis treats encrypted variables. This token needs to be generated by someone with access to the repo

Generating a token

Go to the Personal access tokens section of Github, and create a now token with repo permissions only. If it’s a public repo, then public_repo permissions will suffice. Name it something memorable, and copy it down somewhere safe when you are shown it, as you’re only shown it the once.

Encrypting the token

Important: to ensure you don’t inadvertently leak your token, granting someone else write-access to your repo, you must encrypt this token! Do *not* paste it into .travis.yml without encrypting it first! To encrypt you Github token, you’re need to install Travis CLI locally if you haven’t already, then run

$ travis encrypt GH_TOKEN=put-your-very-secret-github-token-here

This will output the encrypted variable into your console, looking something like:

secure: long string of nonsense here

Copy the entire output to your .travis.yml under the env global section. You should end up with a section like this. It’s ok to have more than one secure environment variable.

env:
  global:
  - secure: that same long string of nonsense

See Travis’s documentation on encrypting environment variables for more information.

Assuming the repo is already set up to be tested in Travis, this should be all you need to set up automatic deployments

Configuring Travis to auto-deploy Javadoc from branches other than master

If you wish to deploy javadoc from a different branch, perhaps a development / test branch, find this line in your .travis.yml

after_success:
  - test $TRAVIS_BRANCH == "master" && bash config/travis/deploydocs.sh

Simply change the value of “master” to the branch you wish to use.