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 "[email protected]"
    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?

[akarnokd]

Many old links point to the rx.Observable and other 1.x classes through http://reactivex.io/RxJava/javadoc/rx/Observable.html, so /javadoc should be cleared cautiously and the generated files require <link rel="canonical" href=""> with the proper 2.x reference appended in a certain way. Also don't bother with 1.x automation, not many versions will be released before EOL.

[akarnokd]

This may work for 2.x: https://docs.travis-ci.com/user/deployment/pages/ but requires unpacking the jar into the proper directories.

[wojtekPi]

@defer

I can take this one.

Are you working on this? If not, I can pick this Issue and create some PoC, but I don't want to duplicate work ;)

[rpmcdougall]

I took a stab at this using https://github.com/ajoberstar/gradle-git-publish and got it to work by generating the javadocs with the gradle task that already existed and then running the gitPublishPush task from setting this new plugin up. I've only got this working on the 2.x docs currently, but will give 1.x a shot later this weekend. If these seems acceptable, I can work on a PR for you all.

Thanks!

Here's the commit where I added the gradle plugin configuration.
rpmcdougall@cccb483

Here are the 2.x docs working.
https://rpmcdougall.github.io/RxJava/

[akarnokd]

Thanks. I will look into that. 1.x is EOL and no need for its javadoc to be automated.

[rpmcdougall]

I added a bit to check for the presence of a github token as well to cover another form of auth to the repo as well.

rpmcdougall@2e306a3

[rpmcdougall]

@akarnokd Thanks for helping me work through the solution I was proposing (This was my first attempt at contributing to open source). I might be borrowing the solution you came up with for some other projects 👍

[akarnokd]

Sure thing @rpmcdougall and thanks for your attempts!

Closing via #5996 .