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:

.. code-block:: bash

  ~/git/flymine $ ./gradlew 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 `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 <https://travis-ci.org>`_, you can deploy the documentation automatically whenever new code is checked into your `master` branch, using `Github Pages <https://pages.github.com/>`_ 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 <https://docs.travis-ci.com/user/environment-variables#defining-encrypted-variables-in-travisyml>`_. This token needs to be generated by someone with access to the repo

Generating a token
____________________
Go to the `Personal access tokens <https://github.com/settings/tokens/new>`_ 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

.. code-block:: bash

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

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

.. code-block:: yaml

  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.

.. code-block:: bash

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

See `Travis's documentation on encrypting environment variables <https://docs.travis-ci.com/user/encryption-keys/>`_ 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`

.. code-block:: yaml

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

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