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.
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.
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.
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
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.
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.
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
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.
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
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.