Scaladoc and publishing it

[ches]

This branch contains no functional changes, so I [ci skip]ed it—you can trust me that the SBT configuration works, or try it out yourself 😄

What this does

• Adds a lot of absent Scaladoc, including important types like Client and HttpAdapter.
• Sets up generating versioned Scaladoc with sbt-site (note: uses the 1.0.0-RC3 version of the plugin, so see that README for reference).
• Sets up publishing the Scaladoc to http://keenlabs.github.io/KeenClient-Scala/ with GitHub Pages, via sbt-ghpages. Here's a test version on my fork.
• Wires links to source code in the Scaladoc to the matching version on GitHub, using master if it's a SNAPSHOT.

Adding a lot of documentation basically amounted to a close-reading of the code, and I added a lot of todos along the way… That might be noisy but my goal would be for those to be eliminated by 1.0 or at worst moved out of documentation comments. I welcome thoughts on any of those todos inline.

Scaladoc does pretty smart inheritance of documentation from parent classes/traits automatically, with @inheritdoc only needed if you wish to append to a parent's doc. So, I moved some documentation to parents like EventStore so implementors can understand how they're supposed to work.

Caveats

One little piece of the story is unfortunately broken currently: publishing multiple versions of the API docs to GitHub Pages. sbt-site correctly builds into versioned paths like /api/0.6.0/, but sbt-ghpages clobbers all the content in the gh-pages branch every time you publish, leaving only the most recent. I consider this a bug, the documentation of the task specifically says it shouldn't do that. I'm going to try to submit a pull request to change it, but the project has been inactive so it might take awhile.

This doesn't really diminish the usefulness of everything done here so far, it just means that unfortunately people may stumble across rotted links to docs for earlier versions until this gets resolved. Once there's a fix we'll just need to update sbt-ghpages and everything should keep working, without the loss of doc versions from then on.

Initializing the project's GitHub Pages

Ignore the sbt-ghpages instructions for creating the gh-pages branch—they're prone to potentially dangerous error. Here is what I did to test on my fork, using GitHub's official documentation except with an empty commit to establish the branch:

# Use a fresh clone as advised
$ cd /tmp
$ git clone [email protected]:keenlabs/KeenClient-Scala.git
$ cd KeenClient-Scala

# Create branch with no history or content
$ git checkout --orphan gh-pages
$ git rm -rf .

# Establish the branch existence
$ git commit --allow-empty -m "Initialize gh-pages branch"
$ git push origin gh-pages

# Go back to a "real" branch, or better yet just nuke the /tmp clone now
$ git checkout master

Create and push the branch before trying to run sbt ghpagesPushSite—under the hood it actually clones a sandbox copy of the repo beneath ~/.sbt/ghpages, and it expects the branch to already exist so it can check it out. The documentation doesn't cover these subtleties very well, but the sandbox approach is nice since it avoids potentially bungling up things in your working copy when it's automating the gh-pages branch dance.

Remember that we still have version at 0.6.0 in build.sbt currently, so you might want to change that to an 0.7.0-SNAPSHOT or something before publishing docs, since there have been changes since the last release.

[ches]

Hmm, it seems like the published docs include a full local file path that breaks the links to source code—see for example this page on the Source: Client.scala link.

The basedir.getAbsolutePath in the SBT config looks suspicious at first, but this is the same approach I've found in several projects and I can't reproduce the full local path behavior when I test locally (or published to my own gh-pages). This discussion suggests that if -sourcepath "is not a prefix of the file path, then you just get an absolute path", or put the other way around, I believe scaladoc tries to make the FILE_PATH template placeholder relative if -sourcepath is a descendent of the working directory.

My unfounded suspicion (not reading source or trying to test yet…) is that maybe the scaladoc tool doesn't handle one of these situations well:

1. Either the working directory or sourcepath contains spaces.
2. Either the working directory or sourcepath contains a symlink at some level.

There is a space in the generated path. @terryhorner could you try copying your checkout to, say, /tmp and checking the source links after sbt previewSite from there?

[terrhorn]

Derp! My bad on that one @ches. Should be all fixed up now.

[ches]

No worries, thanks! Did that fix it (running from a path with no spaces, or symlinks)? Wondering if this is reported already.

[terrhorn]

Yup, running it from a path with no spaces fixed it.