https://github.com/cchantep/sbt-scaladoc-compiler

:gear: This SBT plugin extracts the Scala examples from the Scaladoc comments, and compile the extracted code.
https://github.com/cchantep/sbt-scaladoc-compiler

sbt sbt-plugin scala scaladoc

Last synced: 11 days ago
JSON representation

:gear: This SBT plugin extracts the Scala examples from the Scaladoc comments, and compile the extracted code.

• Host: GitHub
• URL: https://github.com/cchantep/sbt-scaladoc-compiler
• Owner: cchantep
• License: gpl-2.0
• Created: 2019-12-02T17:01:45.000Z (about 5 years ago)
• Default Branch: master
• Last Pushed: 2022-01-01T15:47:50.000Z (about 3 years ago)
• Last Synced: 2024-10-11T10:22:01.898Z (3 months ago)
• Topics: sbt, sbt-plugin, scala, scaladoc
• Language: Scala
• Homepage:
• Size: 13.7 KB
• Stars: 2
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# SBT scaladoc compiler

This SBT plugin extracts the Scala examples from the Scaladoc comments, and compile the extracted code.

## Motivation

Considering a Scaladoc as bellow:

```scala

package example

/**

 * Foo

 *

 * {{{

 * import example.Foo

 *

 * Foo.bar()

 * }}}

 */

object Foo {

  def bar(): String = "..."

}

```

Using this SBT plugin, the code samples between `{{{` and `}}}` (in Scaladoc started with `/**` and ended with `*/`, in files `*.scala`) will be extracted as test sources, and so compiled/validated by test compilation.

## Get started

This plugin requires SBT 0.13+.

You need to update the `project/plugins.sbt`.

```scala

resolvers ++= Seq(

  "Tatami Releases" at "https://raw.github.com/cchantep/tatami/master/releases")

addSbtPlugin("cchantep" % "sbt-scaladoc-compiler" % "0.3")

```

*See a SBT build [using this plugin](https://github.com/ReactiveMongo/Reactivemongo-BSON/blob/master/project/plugins.sbt).*

Then, any time `test:compile` task is executed in SBT, the Scaladoc examples will be compiled along.

**In case of SBT [Multi-Project](https://www.scala-sbt.org/1.x/docs/Multi-Project.html)**

It may be required to disable this plugin on the aggregation if some examples in files of the sub-project require some depen

dencies specific to the sub-project (not available at the aggregation time).

```scala

lazy val root = Project(id = "...", base = file(".")).

  aggregate(/* ... */).

  disablePlugins(ScaladocExtractorPlugin)

```

## Extraction behaviour

Each code sample need to be standalone:

- all imports explicitly specified,

- no call to private members.

In case a code example must be excluded/skipped, the setting `scaladocExtractorSkipToken` can be used (default: `"// not compilable"`).

```scala

/**

 * Lorem ipsum

 *

 * {{{

 * // not compilable: some details why (as also displayed in Scaladoc)

 * foo bar ... anyway it's not compiled (if any good reason)

 * }}}

 */

def foo(s: String): Int = s.size

```

## Build

This is built using SBT.

    sbt '^ publishLocal'

[![Build Status](https://travis-ci.org/cchantep/sbt-scaladoc-compiler.svg?branch=master)](https://travis-ci.org/cchantep/sbt-scaladoc-compiler)