Hosting Javadocs

Owned by Richard Kareko
Last updated: Feb 07, 2020 by Benjamin Mwalimu Mulyungi
3 min read

The following section describes the steps taken to generate and publish javadocs to github pages.

First the implementing developer should create a gh-pages branch

After creating the gh-pages branch the following actions will have to be carried out by someone with admin access for the OpenSRP repos :-

  1. Create a personal github access token with public_repo permission only to allow travis to deploy the java docs to the gh-pages branch. Instructions can be found here . This has already been done for the OpenSRP projects. No need to create another one at the moment.

  2. Configure a publishing source for the github pages site using directions provided here

  3. If the site has not published i.e you cannot view the projects Readme contents on http://smartregister.org/ {project repo name} , the admin should make a blank commit & push on the gh-pages branch for the project using this command git commit -S -m "Trigger CI" --allow-empty . After the push, the contents of the project's Readme files should be displayed on http://smartregister.org/ {project repo name} url.

  4. Encrypt the gitub token generated on step 1 using the following command travis encrypt GITHUB_TOKEN=actual_github_access_token . Note that this step has to be done in the project directory itself. Encrypted travis values cannot be shared between projects

    • This command will create the github access token and add it to the travis.yml file automatically.

      travis encrypt GITHUB_TOKEN=actual_github_access_token --add

  • You need travis installed on your local environment. Use the following commands:

    • Ubuntu :-

      •  

        sudo apt install ruby ruby-dev sudo gem install travis

    • Mac : -

      • brew install ruby gem update --system gem install travis -v 1.8.8 --no-rdoc --no-ri

The following details steps for setting up travis to generate and publish javadocs to github pages. This can be done by any developer.

This Reveal PR can be used as a template to follow.

  1. Create a branch based on master. This can have any name you deem fit e.g travis-deploy-javadoc

  2. Add a gradle task in the project build file for generating javadocs in the project’s build.gradle file as shown here

    • For a library make sure this gradle task is placed on the library’s build.gradle file and not the sample app’s build.gradle file.

  3. In the travis.yml file add a command for generating the javadocs as shown here on line 53 and 54. This goes in the script section

  4. In the travis.yml file add a github pages provider which will deploy the javadocs to the github pages branch as shown here on line 58 to 64 . The special note of the following variables :-

    1. local_dir

      • This variable specifies the location where the generated javadocs are found in the project structure

    2. branch

      • The branch on which the deployment will be triggered on when a git push is done. Branch created on step 1 e.g

      travis-deploy-javadoc . This will be changed later to master

  5. In the travis.yml file add the encrypted github access token to the global env section as shown here

  6. Push these changes. After a successful build the generated javadocs should be published on http://smartregister.org/{project repo name}

  7. After confirming that the javadocs have been published, change the deploy branch to master as shown here . This is done so as to ensure that publishing of the javadocs is only done after changes are merged to master.