Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Adds automatic doc generation for entire project #118

Merged
merged 3 commits into from

2 participants

@sritchie
Collaborator

Generate docs into target/site with sbt unidoc and publish to http://twitter.github.com/algebird with sbt ghpages-push-site.

If you guys like this, we can get this into scalding, storehaus, summingbird and bijection. I'd rather duplicate these few files than spend more hours fucking with SBT's plugin architecture to bundle them up separately :)

Sam Ritchie added some commits
Sam Ritchie add unidoc 0b81cb6
Sam Ritchie add docgen 4b63109
Sam Ritchie add readme note. c6c293e
@johnynek
Collaborator

Can you push to this branch again and see if it makes the build go green (maybe merge with the fixed develop?)

@sritchie
Collaborator

Looks like it's in the submit queue for travis now.

@johnynek johnynek merged commit 08c8bb3 into develop
@johnynek johnynek deleted the feature/gh_pages branch
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Feb 14, 2013
  1. add unidoc

    Sam Ritchie authored
  2. add docgen

    Sam Ritchie authored
  3. add readme note.

    Sam Ritchie authored
This page is out of date. Refresh to see the latest.
View
2  README.md
@@ -2,6 +2,8 @@
Abstract algebra for Scala. This code is targeted at building aggregation systems (via [Scalding](https://github.com/twitter/scalding) or [Storm](https://github.com/nathanmarz/storm)). It was originally developed as part of Scalding's Matrix API, where Matrices had values which are elements of Monoids, Groups, or Rings. Subsequently, it was clear that the code had broader application within Scalding and on other projects within Twitter.
+See the [current API documentation](http://twitter.github.com/algebird) for more information.
+
## What can you do with this code?
```scala
View
5 project/Build.scala
@@ -1,3 +1,5 @@
+package algebird
+
import sbt._
import Keys._
@@ -5,6 +7,7 @@ object AlgebirdBuild extends Build {
val sharedSettings = Project.defaultSettings ++ Seq(
organization := "com.twitter",
version := "0.1.9-SNAPSHOT",
+ scalaVersion := "2.9.2",
crossScalaVersions := Seq("2.9.2", "2.10.0"),
resolvers ++= Seq(
@@ -62,7 +65,7 @@ object AlgebirdBuild extends Build {
lazy val algebird = Project(
id = "algebird",
base = file("."),
- settings = sharedSettings
+ settings = sharedSettings ++ DocGen.publishSettings
).settings(
test := { }
).aggregate(algebirdTest,
View
43 project/DocGen.scala
@@ -0,0 +1,43 @@
+package algebird
+
+import sbt._
+import Keys._
+
+import com.typesafe.sbt.git.GitRunner
+import com.typesafe.sbt.SbtGit.GitKeys
+import com.typesafe.sbt.SbtSite.{ site, SiteKeys }
+import com.typesafe.sbt.SbtGhPages.{ ghpages, GhPagesKeys => ghkeys }
+import com.typesafe.sbt.SbtGit.GitKeys.gitRemoteRepo
+
+object DocGen {
+ val docDirectory = "target/site"
+
+ def syncLocal = (ghkeys.updatedRepository, GitKeys.gitRunner, streams) map { (repo, git, s) =>
+ cleanSite(repo, git, s) // First, remove 'stale' files.
+ val rootPath = file(docDirectory) // Now copy files.
+ IO.copyDirectory(rootPath, repo)
+ IO.touch(repo / ".nojekyll")
+ repo
+ }
+
+ private def cleanSite(dir: File, git: GitRunner, s: TaskStreams): Unit = {
+ val toClean = IO.listFiles(dir).filterNot(_.getName == ".git").map(_.getAbsolutePath).toList
+ if(!toClean.isEmpty)
+ git(("rm" :: "-r" :: "-f" :: "--ignore-unmatch" :: toClean) :_*)(dir, s.log)
+ ()
+ }
+
+ lazy val unidocSettings: Seq[sbt.Setting[_]] =
+ site.includeScaladoc(docDirectory) ++ Seq(
+ scalacOptions in doc <++= (version, baseDirectory in LocalProject("algebird")).map { (v, rootBase) =>
+ val tagOrBranch = if (v.endsWith("-SNAPSHOT")) "develop" else v
+ val docSourceUrl = "https://github.com/twitter/algebird/tree/" + tagOrBranch + "€{FILE_PATH}.scala"
+ Seq("-sourcepath", rootBase.getAbsolutePath, "-doc-source-url", docSourceUrl)
+ },
+ Unidoc.unidocDirectory := file(docDirectory),
+ gitRemoteRepo := "git@github.com:twitter/algebird.git",
+ ghkeys.synchLocal <<= syncLocal
+ )
+
+ lazy val publishSettings = site.settings ++ Unidoc.settings ++ ghpages.settings ++ unidocSettings
+}
View
54 project/Unidoc.scala
@@ -0,0 +1,54 @@
+package algebird
+
+import sbt._
+import sbt.Keys._
+import sbt.Project.Initialize
+
+/** Borrowed from https://github.com/akka/akka/blob/master/project/Unidoc.scala */
+object Unidoc {
+ val unidocDirectory = SettingKey[File]("unidoc-directory")
+ val unidocExclude = SettingKey[Seq[String]]("unidoc-exclude")
+ val unidocAllSources = TaskKey[Seq[Seq[File]]]("unidoc-all-sources")
+ val unidocSources = TaskKey[Seq[File]]("unidoc-sources")
+ val unidocAllClasspaths = TaskKey[Seq[Classpath]]("unidoc-all-classpaths")
+ val unidocClasspath = TaskKey[Seq[File]]("unidoc-classpath")
+ val unidoc = TaskKey[File]("unidoc", "Create unified scaladoc for all aggregates")
+
+ lazy val settings = Seq(
+ unidocDirectory <<= crossTarget / "unidoc",
+ unidocExclude := Seq.empty,
+ unidocAllSources <<= (thisProjectRef, buildStructure, unidocExclude) flatMap allSources,
+ unidocSources <<= unidocAllSources map { _.flatten },
+ unidocAllClasspaths <<= (thisProjectRef, buildStructure, unidocExclude) flatMap allClasspaths,
+ unidocClasspath <<= unidocAllClasspaths map { _.flatten.map(_.data).distinct },
+ unidoc <<= unidocTask
+ )
+
+ def allSources(projectRef: ProjectRef, structure: Load.BuildStructure, exclude: Seq[String]): Task[Seq[Seq[File]]] = {
+ val projects = aggregated(projectRef, structure, exclude)
+ projects flatMap { sources in Compile in LocalProject(_) get structure.data } join
+ }
+
+ def allClasspaths(projectRef: ProjectRef, structure: Load.BuildStructure, exclude: Seq[String]): Task[Seq[Classpath]] = {
+ val projects = aggregated(projectRef, structure, exclude)
+ projects flatMap { dependencyClasspath in Compile in LocalProject(_) get structure.data } join
+ }
+
+ def aggregated(projectRef: ProjectRef, structure: Load.BuildStructure, exclude: Seq[String]): Seq[String] = {
+ val aggregate = Project.getProject(projectRef, structure).toSeq.flatMap(_.aggregate)
+ aggregate flatMap { ref =>
+ if (exclude contains ref.project) Seq.empty
+ else ref.project +: aggregated(ref, structure, exclude)
+ }
+ }
+
+ def unidocTask: Initialize[Task[File]] = {
+ (compilers, cacheDirectory, unidocSources, unidocClasspath, unidocDirectory, scalacOptions in doc, streams) map {
+ (compilers, cache, sources, classpath, target, options, s) => {
+ val scaladoc = new Scaladoc(100, compilers.scalac)
+ scaladoc.cached(cache / "unidoc", "main", sources, classpath, target, options, s.log)
+ target
+ }
+ }
+ }
+}
View
3  project/plugins.sbt
@@ -0,0 +1,3 @@
+resolvers += "jgit-repo" at "http://download.eclipse.org/jgit/maven"
+
+addSbtPlugin("com.typesafe.sbt" % "sbt-ghpages" % "0.5.0")
Something went wrong with that request. Please try again.