diff --git a/build.sbt b/build.sbt index 7d92954c..d7f75ab4 100644 --- a/build.sbt +++ b/build.sbt @@ -106,14 +106,13 @@ val tutPath = settingKey[String]("Path to tutorials") lazy val docs = project .settings(moduleName := "finagle-postgres-docs", buildSettings) - .enablePlugins(GhpagesPlugin, TutPlugin, ScalaUnidocPlugin) + .enablePlugins(GhpagesPlugin, ScalaUnidocPlugin) .settings( scaladocVersionPath := ("api/" + version.value), scaladocLatestPath := (if (isSnapshot.value) "api/latest-snapshot" else "api/latest"), tutPath := "doc", includeFilter in makeSite := (includeFilter in makeSite).value || "*.md" || "*.yml", - addMappingsToSiteDir(tut in Compile, tutPath), addMappingsToSiteDir( mappings in (ScalaUnidoc, packageDoc), scaladocLatestPath diff --git a/docs/src/main/tut/02-basic-usage.md b/docs/src/main/tut/02-basic-usage.md index 3559fea7..7635b59b 100644 --- a/docs/src/main/tut/02-basic-usage.md +++ b/docs/src/main/tut/02-basic-usage.md @@ -9,12 +9,12 @@ Finagle-postgres follows the conventions of the rest of the finagle ecosystem. T the client builder accessed by `com.twitter.finagle.Postgres.Client()`: -```tut:invisible +```scala mdoc:invisible import com.twitter.util.Await object dontrun { ``` -```tut:book +```scala mdoc import com.twitter.finagle.Postgres val client = Postgres.Client() @@ -27,7 +27,7 @@ val client = Postgres.Client() .newRichClient("localhost:5432") ``` -```tut:invisible +```scala mdoc:invisible Await.result(client.close()) } diff --git a/docs/src/main/tut/03-simple-queries.md b/docs/src/main/tut/03-simple-queries.md index 5ae1a0a7..c58c24b2 100644 --- a/docs/src/main/tut/03-simple-queries.md +++ b/docs/src/main/tut/03-simple-queries.md @@ -12,7 +12,7 @@ could be a vector for SQL injection attacks. Still, it can be useful to try them out. -```tut:invisible +```scala mdoc:invisible import com.twitter.finagle.Postgres import com.twitter.util.Await // create the client based on environment variables @@ -29,7 +29,7 @@ val client = { Await.result(client.execute("DROP TABLE IF EXISTS demo")) ``` -```tut:book +```scala mdoc import com.twitter.util.Await // execute a query that has no results - i.e. CREATE TABLE, UPDATE, INSERT, DELETE, etc. @@ -92,6 +92,6 @@ are happy to accept instances for built-in Scala or Java types into finagle-post Next, read about [Parameterized Queries](04-parameterized-queries.html) -```tut:invisible +```scala mdoc:invisible Await.result(client.close()) ``` diff --git a/docs/src/main/tut/04-parameterized-queries.md b/docs/src/main/tut/04-parameterized-queries.md index 345eb5ef..19aff761 100644 --- a/docs/src/main/tut/04-parameterized-queries.md +++ b/docs/src/main/tut/04-parameterized-queries.md @@ -8,7 +8,7 @@ layout: default Since most database-driven applications will need to use user-supplied data as parameters to their queries, finagle-postgres supports parameterized queries through its prepared statement interface: -```tut:invisible +```scala mdoc:invisible import com.twitter.finagle.Postgres import com.twitter.util.Await // create the client based on environment variables @@ -24,7 +24,7 @@ val client = { Await.result(client.execute("DROP TABLE IF EXISTS demo")) ``` -```tut:book +```scala mdoc import com.twitter.util.Await // execute a query that has no results - i.e. CREATE TABLE, UPDATE, INSERT, DELETE, etc. @@ -50,6 +50,6 @@ query, which means they won't be a potential vector for SQL injection attacks. Next, read about [Automatic case class marshalling](05-automatic-case-class-marshalling.html) -```tut:invisible +```scala mdoc:invisible Await.result(client.close()) ``` \ No newline at end of file diff --git a/docs/src/main/tut/05-automatic-case-class-marshalling.md b/docs/src/main/tut/05-automatic-case-class-marshalling.md index a39d8c4c..bd28e207 100644 --- a/docs/src/main/tut/05-automatic-case-class-marshalling.md +++ b/docs/src/main/tut/05-automatic-case-class-marshalling.md @@ -11,7 +11,7 @@ function: `Future[Seq[T]]`. This typically results in a pattern like this: -```tut:invisible +```scala mdoc:invisible import com.twitter.finagle.Postgres import com.twitter.util.Await // create the client based on environment variables @@ -30,7 +30,7 @@ Await.result(client.prepareAndExecute("CREATE TABLE demo(id serial PRIMARY KEY, Await.result(client.prepareAndExecute("INSERT INTO demo (foo) VALUES ($1)", "foo")) ``` -```tut:book +```scala mdoc case class Demo(id: Int, foo: String) val select = client.prepareAndQuery("SELECT * FROM demo") { @@ -47,7 +47,7 @@ As you can see, this probably gets verbose and repetitive for rows which have a there must be a better way, and thanks to [shapeless](https://github.com/milessabin/shapeless), there is! Importing `com.twitter.finagle.postgres.generic._` enriches `client` with an additional operation, `queryAs`: -```tut:book +```scala mdoc import com.twitter.finagle.postgres.generic._ val result = Await.result { @@ -61,6 +61,6 @@ to instead do nothing to convert column names. Next, read about [Query DSL](06-query-dsl.html) -```tut:invisible +```scala mdoc:invisible Await.result(client.close()) ``` \ No newline at end of file diff --git a/docs/src/main/tut/06-query-dsl.md b/docs/src/main/tut/06-query-dsl.md index fbfecad9..29ab50c4 100644 --- a/docs/src/main/tut/06-query-dsl.md +++ b/docs/src/main/tut/06-query-dsl.md @@ -11,7 +11,7 @@ queries. The DSL lives in the `com.twitter.finagle.postgres.generic._` import. The abstraction provided is the `Query[T]` data type, which captures a query and its parameters. It's used in conjunction with the `QueryContext` implicit enrichment, which provides a `sql` String interpolator: -```tut:invisible +```scala mdoc:invisible import com.twitter.finagle.Postgres import com.twitter.util.Await // create the client based on environment variables @@ -30,7 +30,7 @@ Await.result(client.prepareAndExecute("INSERT INTO demo(foo) VALUES ($1)", "foo" case class Demo(id: Int, foo: String) ``` -```tut:book +```scala mdoc import com.twitter.finagle.postgres.generic._ def insert(foo: String) = sql"INSERT INTO demo (foo) VALUES ($foo)" @@ -57,7 +57,7 @@ For other types of values (like single-column results, for example) there is als from the current type of a query (i.e. `Row` for a freshly created `Query[Row]`) to some other type `T`, and appends the function to the continuation that will map the rows. For example: -```tut:book +```scala mdoc def count(input: String) = sql"SELECT count(*) FROM demo WHERE foo = $input".map { row => row.get[Long]("count") } @@ -71,6 +71,6 @@ class` with a `count` column); since there is only one row expected, we also `ma just the first row using `_.head`. A more in-depth query DSL is planned, but this is the extent of what's currently offered. -```tut:invisible +```scala mdoc:invisible Await.result(client.close()) ``` \ No newline at end of file diff --git a/project/MdocSitePlugin.scala b/project/MdocSitePlugin.scala new file mode 100644 index 00000000..c0b092b7 --- /dev/null +++ b/project/MdocSitePlugin.scala @@ -0,0 +1,30 @@ +import com.typesafe.sbt.site.SitePlugin.autoImport._ +import mdoc.MdocPlugin, MdocPlugin.autoImport._ +import sbt._, Keys._ +import sbt.plugins.{JvmPlugin, SbtPlugin} + +/** Provides glue to integrate mdoc with sbt-site. */ +object MdocSitePlugin extends AutoPlugin { + override def trigger = allRequirements + + override def requires = JvmPlugin && MdocPlugin + + object autoImport { + val mdocSite = taskKey[Seq[(File, String)]]("create mdoc documentation in a way that lets sbt-site grab it") + val mdocSiteOut = settingKey[String]("name of the directory in which sbt-site will store mdoc documentation") + } + + import autoImport._ + + override def projectSettings: Seq[Setting[_]] = Seq( + mdocSite := { + mdoc.toTask(" ").value + val out = mdocOut.value + for { + (file, name) <- out ** AllPassFilter --- out pair Path.relativeTo(out) + } yield file -> name + }, + mdocSiteOut := "./", + addMappingsToSiteDir(mdocSite, mdocSiteOut) + ) +} diff --git a/project/plugins.sbt b/project/plugins.sbt index 44864eed..f4aeb70b 100644 --- a/project/plugins.sbt +++ b/project/plugins.sbt @@ -3,7 +3,7 @@ resolvers ++= Seq( Classpaths.sbtPluginReleases ) -addSbtPlugin("org.tpolecat" % "tut-plugin" % "0.6.13") +addSbtPlugin("org.scalameta" % "sbt-mdoc" % "2.2.21") addSbtPlugin("com.github.sbt" % "sbt-release" % "1.0.15") addSbtPlugin("org.xerial.sbt" % "sbt-sonatype" % "3.9.7") addSbtPlugin("com.jsuereth" % "sbt-pgp" % "1.1.2")