Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [soc-dev] [recommenders-dev] [GSoC] Livedoc Weekly Report 06 & Weekly Report 07
Hi Michael,
Hi recommenders-dev,
Hi soc-dev,

i'm sorry for the late answer, your mail vanished in the depth of my mail box :/
For the Livedoc Weekly Report 07, I've decided to write a little hands-on on the Google Analytics Provider for you :)
For tl;dr, just jump to Result :)
 
What's it all about?
As you may know, with Livedoc you can enrich your good old Javadoc with source-code statistics from Code Recommenders, making them available directly into your HTML web page and not only in your Eclipse IDE.
Our goal is to provide an easy entry point for your (new) developers to your Java API, lowering the entrance barrier for them to write some source code.
However, this is a strictly one-way move:

Your Java source code --> Gather source code statistics --> Produce Javadoc with them --> Upload to the internet  --> Read by your users/developers.

There's no possibility for an automated way back, allowing you to investigate how your users deal with your documentation. But happily there's a way to change this.
With Google Analytics we can gather user statistics from your Javadoc documentation, as Javadoc is plain HTML (maybe uploaded to a website).
This will allow you to answer questions like "How much time spend the average visitor on class Foo?"

How to be done?
Let's take a look at an example for JDK7 documentation.

Preparation:
As stated in the Livedoc Readme, you need three objects for a successful Livedoc run:
  1. A Maven repository for source files (packaging: jar, classifier: sources)
  2. A Maven repository for Code Recommenders models
  3. An artifact coordinate identifying the JAR file you wish to create Livedoc for

1. In the case of JDK7, we don't have an online maven repository containing the source files of the JDK, thus we need to create a local one.
To achieve this, just grab your JDK’s source archive (src.zip in your JDK installation folder for Oracle JDKs) and type the following (for Java version 1.7):

mvn deploy:deploy-file -Durl=file:/some/folder/repo -Dfile=src.zip -DgroupId=jre -DartifactId=jre -Dversion=1.7.0 -Dpackaging=jar -Dclassifier=sources

After that, you can use

/some/folder/repo
as your source code repository for Livedoc (on JDK runs).

2. For the JDK, we can use the Code Recommenders model repository of Eclipse Luna:

http://download.eclipse.org/recommenders/models/luna/

3. This should be easy:
As we deployed the JRE artifact into our local maven repository on step 1, we already know the artifact coordinate (as we defined it by groupId, artifactId and version ourselves).
Syntax is GROUP_ID:ARTIFACT_ID:VERSION, so:

jre:jre:1.7.0

(4.)
Additionally, for the Google Analytics provider, you'll need a Google Analytics Account set-up and Tracking ID:

https://support.google.com/analytics/answer/1008015?hl=en

For this example, let's say our Tracking ID is 123ABC.

Throwing it all together:
Now, as you have all 3(+1) objects together, head over to http://download.eclipse.org/recommenders.incubator/livedoc/products/milestones/?d, and download Livedoc for your OS resp. architecture. After extracting, you can run the following command line:

./livedoc jre:jre:1.7.0 -sr /some/folder/repo -mr http://download.eclipse.org/recommenders/models/luna/ -d ./output -p analytics [123ABC]

Result
Livedoc will produce Javadoc for you and integrate this required Google Analytics Tracking Code:
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', '123ABC']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/_javascript_'; ga.async = true;
    ga.src = "" == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

After uploading your created Javadoc HTML to your website, you can watch your visitors statistics in your Google Analytics Account:


What happens next?

Currently, there are 3 features on the roadmap for the 0.11 release:
  • JDK 8 Javadoc Support
  • The Xdoclint feature of JDK 8
  • An out-of-the-box usecase

This week, I'll focus on the JDK 8 support (Bug 432418)
However, I'd like to lay focus on a discussion for Bug 435940, check out the bugtracker :)

I hope you enjoyed reading this little hands-on, try Livedoc yourself and don't hesitate to send me your opinions about it :)

Best regards,
Patrick

On Wed, 11 Jun 2014 17:14:05 +0200, Michael Kutschke <kutschke.michael@xxxxxxxxxxxxxx> wrote:

Hi Patrick,

a Google analytics provider? Sounds interesting, care to elaborate?

Regards,
Michael

Am 11.06.2014 17:04 schrieb "Patrick Gottschaemmer" <mail@xxxxxxxxxxxxxxxxx>:
Hi recommenders-dev,
Hi soc-dev,

this is your weekly status report for the GSoC 2014 project Livedoc [XXL].

What happened last week?

Last week (as promised) we released Livedoc 0.10. The current milestone is avaiable here:

http://download.eclipse.org/recommenders.incubator/livedoc/products/milestones/?d

The core features of the 0.10 Release are:

The new features are described (as always) in the documentation:

http://download.eclipse.org/recommenders.incubator/livedoc/docs/milestones/readme.html

 
What will be (hopefully) done next week?

Next week I will implement an out of the box usecase for Livedoc and start to make Livedoc JDK 8 compatible.
This will be a breaking change, as we (mabye) have to drop the JDK 7 compatibility.

Best regards,
Patrick

_______________________________________________
recommenders-dev mailing list
recommenders-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/recommenders-dev



_______________________________________________
recommenders-dev mailing list
recommenders-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/recommenders-dev

Back to the top