Automate Publishing of Javadocs

[benjchristensen]

Javadocs should be auto-generated for snapshot and final release builds.

If it needs to be a shell script it can be incorporated into the Travis build process here: https://github.com/ReactiveX/RxJava/blob/1.x/gradle/buildViaTravis.sh

Javadocs get published to gh-pages here: https://github.com/ReactiveX/RxJava/tree/gh-pages/javadoc

Each version should go in it's own directory. Whatever the latest version is should also be in the root. There should also be a /snapshot/ folder for the latest snapshot.

[benjchristensen]

Here is the hack of a script I use to generate Javadocs:

#!/bin/sh

/PATH/TO/jdk7/javadoc -windowtitle "RxJava Javadoc 1.0.2" -sourcepath /PATH/HERE/RxJavaOrigin/src/main/java/ -d /PATH/HERE/RxJavaPages/javadoc/ -doclet org.benjchristensen.doclet.DocletExclude -docletpath /PATH/HERE/doclet-exclude.jar -classpath /PATH/HERE/com.google.code.findbugs/annotations/2.0.0/jar/d8dff1d83a79f0c0609c360f02bcd2f2fc1f1369/annotations-2.0.0.jar:/PATH/HERE/com.google.code.findbugs/jsr305/2.0.0/jar/516c03b21d50a644d538de0f0369c620989cd8f0/jsr305-2.0.0.jar:/PATH/HERE/com.google.guava/guava/11.0.1/jar/57b40a943725d43610c898ac0169adf1b2d55742/guava-11.0.1.jar:/PATH/HERE/com.netflix.archaius/archaius-core/0.4.1/jar/69e956ddf4543c989461352a214f32a014abd64a/archaius-core-0.4.1.jar:/PATH/HERE/com.netflix.servo/servo-core/0.4.20/jar/383048e0053cbfb9bc55b495d6b3acbc22acc3eb/servo-core-0.4.20.jar:/PATH/HERE/commons-configuration/commons-configuration/1.8/jar/6cce40435bcd8018018f16898de01976b319941a/commons-configuration-1.8.jar:/PATH/HERE/commons-lang/commons-lang/2.6/jar/ce1edb914c94ebc388f086c6827e8bdeec71ac2/commons-lang-2.6.jar:/PATH/HERE/commons-logging/commons-logging/1.1.1/jar/5043bfebc3db072ed80fbd362e7caf00e885d8ae/commons-logging-1.1.1.jar:/PATH/HERE/junit/junit/4.10/jar/e4f1766ce7404a08f45d859fb9c226fc9e41a861/junit-4.10.jar:/PATH/HERE/org.hamcrest/hamcrest-core/1.1/jar/860340562250678d1a344907ac75754e259cdb14/hamcrest-core-1.1.jar:/PATH/HERE/org.slf4j/slf4j-api/1.7.0/jar/385fd3fda5deeec8f232b93f85c7118eb30a3f55/slf4j-api-1.7.0.jar rx rx.exceptions rx.functions rx.observables rx.observers rx.plugins rx.schedulers rx.subjects rx.subscriptions rx.annotations

[benjchristensen]

Related to this is #1502

[benjchristensen]

This is related to the lack of javadoc versions being posted: #2457

[benjchristensen]

Would still love to have someone help make this happen!

[hyleung]

One one of my own repos, I was able to automate javadoc publishing to gh-pages using this approach:

http://benlimmer.com/2013/12/26/automatically-publish-javadoc-to-gh-pages-with-travis-ci/

In my case, I had my publishing script hooked up to the after_success phase in my Travis build.

My script looks something like this (javadoc generation was is already done in an earlier phase):

#!/bin/bash

if [ "$TRAVIS_BRANCH" == "master" ] && [ "$TRAVIS_PULL_REQUEST" == "false" ]; then
    echo "Cloning gh-pages..."
    cd build
    git clone --quiet --branch=gh-pages https://${GH_TOKEN}@github.com/hyleung/rx-testkit gh-pages 

    cd gh-pages
    git config --local user.email "travis@travis-ci.org"
    git config --local user.name "travis ci"

    rsync -r --delete ../docs/javadoc/ ./javadoc

    printf "Date: $(date)\nBuild: $TRAVIS_BUILD_NUMBER"  > lastupdated
    git add -u .
    git add .

    git commit -m "Javadoc for travis build: $TRAVIS_BUILD_NUMBER auto-pushed to gh-pages"

    echo "Pushing changes to remote"
    git push

    cd ..
    rm -rf gh-pages
fi

I used rsyncwith the --delete flag because it (apparently) deletes any files that aren't in the source directory. Possibly not what you're looking for if you are going to have subdirectories with the docs for each of the versions.

[defer]

I can take this one. I'm a bit confused over the deployment part, 2.x and 1.x get deployed to /.

But then, they get deployed to javadoc/ as well. 1.x and 2.x can coexist due to different namespaces but the 1.x files are unreachable from the index, in that case is there a point in deploying them?