Compiler-verified docs/examples about cats HOT 14 CLOSED

Yes! 💯

from cats.

👍 We had very good experience with sbt-doctest in scalaz-stream.

from cats.

So I have to confess that my experience with Scala libraries is that I find markdown guides/docs to be a lot easier to read/use than ScalaDocs. Am I alone here?

I think we probably want to use sbt-doctest for ScalaDoc, but I also want to try to have some kind of narrative user guide document that is verified using tut as well.

from cats.

I guess we should also set up a gh-pages branch to publish all this fantastic typechecked documentation. Should that be a distinct issue?

from cats.

Yeah, let's open another issue for gh-pages.

from cats.

sbt-pamflet is the thing that @tpolecat said was "like tut but Eugene knew what he was doing". It looks promising.

If I recall correctly, tut has some features missing in sbt-pamflet like imports that carry through the whole page and the ability to show examples that intentionally don't compile. I think the main problem with tut right now is that it puts scalaz 7.1 onto the user's classpath which causes issues for users on previous versions of scalaz. @tpolecat do you envision your tut work being incorporated into sbt-pamflet, or do you think these will remain separate projects?

from cats.

@ceedubs why is scalaz 7.1 a problem here?

from cats.

@stew I suppose that wouldn't be a problem for cats.

from cats.

@ceedubs I haven't really given it any thought. tut does have some features Eugene's thing doesn't have, and as @stew noted the scalaz dep doesn't matter for us. I'm not really a fan of pamflet output; it's great for linear storytelling but I don't think it is as effective for technical doc. I also click on the enormous margins ALL THE TIME and spend most of my time trying to figure out what just happened. But that's just me.

tut has the benefit of being very very simple, and we can change it freely to suit our selfish needs. We would need to set up the gh-pages (#44) to use jekyll to render markdown since tut doesn't do that.

I'm happy to set this up but I won't have time for a few days.

from cats.

👍 to tut, I think the fact that we clearly have the tut authors attention will come in handy.

I have taken ownership of #44 and I'll submit a PR this evening which sets up gh-pages with jekyll, I have a start on this, I just need to move it along a little farther

from cats.

It sounds like there's a consensus on tut. Let's make it happen!

from cats.

@tpolecat we have some gh-pages now as #44 is closed, I heard you might have some experience with tut. Can you get us started?

from cats.

Yeah I'll ping you after the sun comes up to get the story on gh-pages.

from cats.

This was finished a while ago! http://non.github.io/cats/

from cats.