Documentation site overhaul #576
Conversation
| @@ -32,3 +32,11 @@ before_cache: | |||
| - du -h -d 2 $HOME/.sbt/ | |||
| - find $HOME/.sbt -name "*.lock" -type f -delete | |||
| - find $HOME/.ivy2/cache -name "ivydata-*.properties" -type f -delete | |||
|
|
|||
There was a problem hiding this comment.
this webhook reports our build status to gitter.
| <your code> | ||
| ``` | ||
|
|
||
| (Please replace `toot` with `tut`!) `tut` will evaluate your code as if you'd pasted it into a REPL and insert each line's results in the output. State persists across `tut` code blocks, so feel free to alternate code blocks with text discussion. See the [tut README](https://github.com/tpolecat/tut) for more information on the various options you can use to customize your code blocks. |
There was a problem hiding this comment.
this was annoying... if I write tut the build will fail.
| @@ -194,7 +194,7 @@ object ExpHist { | |||
|
|
|||
| // Drops all buckets with an expired timestamp, based on the | |||
| // configured window and the supplied current time. | |||
| def dropExpired(buckets: Vector[Bucket], currTime: Timestamp): (Long, Vector[Bucket]) = | |||
| private[algebird] def dropExpired(buckets: Vector[Bucket], currTime: Timestamp): (Long, Vector[Bucket]) = | |||
There was a problem hiding this comment.
we haven't published yet, so it's fine to break here.
| @@ -31,38 +31,6 @@ trait Cuber[I] { | |||
| def apply(in: I): TraversableOnce[K] | |||
| } | |||
|
|
|||
| /** | |||
There was a problem hiding this comment.
I moved Roller into its own file.
| def apply(in: I): TraversableOnce[K] | ||
| } | ||
|
|
||
| object Roller { |
There was a problem hiding this comment.
this data structure has no changes. I moved it out of Cuber.scala.
| menu_type: typeclasses | ||
|
|
||
| - title: Monad and Friends | ||
| url: typeclasses/functor.html |
There was a problem hiding this comment.
open to suggestions on the ordering here!
| --- | ||
|
|
||
| # Learning Algebird Monoids at the REPL | ||
|
|
There was a problem hiding this comment.
I broke all of these out into their own files.
| @@ -1,75 +1,29 @@ | |||
| # Abstract Algebra | |||
There was a problem hiding this comment.
these get their own files.
| --- | ||
| layout: docs | ||
| title: "Abstract Algebra" | ||
| section: "typeclasses" |
There was a problem hiding this comment.
and now this is going to become a discussion of why abstract algebra is useful in programming
| addSbtPlugin("com.github.gseitz" % "sbt-release" % "1.0.0") | ||
| addSbtPlugin("com.jsuereth" % "sbt-pgp" % "1.0.0") | ||
| addSbtPlugin("com.typesafe" % "sbt-mima-plugin" % "0.1.11") | ||
| addSbtPlugin("com.typesafe.sbt" % "sbt-ghpages" % "0.5.3") | ||
| addSbtPlugin("com.typesafe.sbt" % "sbt-scalariform" % "1.3.0") | ||
| addSbtPlugin("org.scoverage" % "sbt-scoverage" % "1.3.5") | ||
| addSbtPlugin("org.tpolecat" % "tut-plugin" % "0.4.4") |
There was a problem hiding this comment.
we don't need this explicit dependency. sbt-microsites upgrades will bring it along for the ride.
| *(Note - don't use this, use [cats](https://github.com/typelevel/cats))* | ||
|
|
||
| Simple implementation of an `Applicative` type-class. There are many choices for the canonical second operation (`join`, `sequence`, `joinWith`, `ap`), | ||
| all equivalent. For a `Functor` modeling concurrent computations with failure, like `Future`, combining results with `join` can save a lot of time over combining with `flatMap`. (Given two operations, if the second fails before the first completes, one can fail the entire computation right then. With `flatMap`, one would have to wait for the first operation to complete before failing it.) |
There was a problem hiding this comment.
Given two operations, if the second fails before the first completes, one can fail the entire computation right then. With `flatMap`, one would have to wait for the first operation to complete before failing it.
This isn't quite true - if you want your ap/zip to agree with flatMap, you have to wait on the first one to fail, even if the 2nd fails, so that you can surface the error from the first. If the first fails, then you can bail out of the 2nd one early, but not vice versa.
There was a problem hiding this comment.
You can do this ONLY if the Eq[Error] is the trivial one: eqv(a, b) == true.
But yeah, not strictly true in the way the laws are usually written.
Current coverage is 64.72% (diff: 100%)@@ develop #576 diff @@
==========================================
Files 111 111
Lines 4572 4572
Methods 4154 4154
Messages 0 0
Branches 379 379
==========================================
+ Hits 2950 2959 +9
+ Misses 1622 1613 -9
Partials 0 0
|
|
💥 and looks like all new docs compile, as expected! |
|
lgtm modulo the minor fixup @tixxit suggests |
This PR adds a lot of documentation. I love to keep PRs small, but it's not worth it for a non-code change like this.
Preview of the documentation site, published to my fork's github page: https://sritchie.github.io/algebird/
Motivation
My goal here was to set up a structure that would allow others to help me with the massive task of documenting algebird via
tut. It's much more obvious now how to contribute than it was before - find a page that's either empty or poorly documented, click the "edit" link, write some code and send a PR from your browser.We're sort of back at wiki status, except we have excellent placeholders for every documentation page we need, AND any code snippets users add will get compiled in the build and can't go out of date. So good!
Changes
CONTRIBUTING.mdon how to contribute documentation.travis.ymlto report build status to our gitter channelREADME.mdExpHistprivate[algebird], so they don't pollute the scaladocRollerinto its own filetut