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:
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 flymine/webapp/build/javadoc.
Intermine Javadoc#
If you just want to browse the docs, you can see the most recent version at http://intermine.org/intermine/.
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 need to install Travis CLI locally if you haven't already, then run:
This will output the encrypted variable into your console, looking something like:
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.
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
Simply change the value of "master" to the branch you wish to use.