Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cchantep/sbt-hl-compiler
:gear: SBT plugin to extract code sample from documentation files and compile/validation them
https://github.com/cchantep/sbt-hl-compiler
markdown sbt-plugin scala
Last synced: 28 days ago
JSON representation
:gear: SBT plugin to extract code sample from documentation files and compile/validation them
- Host: GitHub
- URL: https://github.com/cchantep/sbt-hl-compiler
- Owner: cchantep
- License: gpl-2.0
- Created: 2015-08-16T11:17:20.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2024-09-17T19:04:10.000Z (about 2 months ago)
- Last Synced: 2024-09-17T23:31:33.363Z (about 2 months ago)
- Topics: markdown, sbt-plugin, scala
- Language: Scala
- Homepage:
- Size: 59.6 KB
- Stars: 1
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SBT highlight compiler
This SBT plugin extracts the Scala examples from a markdown/jekyllrb documentation, and compile the extracted codes, to keep the documentation valid.
## Motivation
Considering a documentation using a markdown format with some Scala code samples as following.
This is a markdown documentation with a code sample.
```scala
val foo = List("Bar", "Lorem", "Ipsum")
```
Using this SBT plugin, the code can be extracted in a generated `.scala` file, and then compiled to be sure it's valid.
## 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-hl-compiler" % "0.8")
```
By default, it will scan all the `*.md` files in the base directory.
The following options are available.
```scala
highlightStartToken := "{% highlight scala %}"
// Token to detect the start of a Scala code sample.
// Can be defined in the scope ThisBuild
// Default: "```scala"
highlightEndToken := "{% endhighlight %}"
// Token to detect the end of a Scala code sample.
// Default: "```"
highlightDirectory := baseDirectory.value / "doc"
// The directory scanned for the documentation files.
// Default: project base directory
includeFilter in doc := "*.ext"
// Default: "*.md"
excludeFilter in doc := "_excludes"
// Default: undefined
```
This plugin also append the `highlightDirectory` to the `watchSources` settings, so a documentation build is triggered each time a source document is updated.
*See a SBT build [using this plugin](https://github.com/ReactiveMongo/reactivemongo-site/blob/gh-pages/build.sbt).*
**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 dependencies specific to the sub-project (not available at the aggregation time).
```scala
lazy val root = Project(id = "...", base = file(".")).
aggregate(/* ... */).
disablePlugins(HighlightExtractorPlugin)
```
## Extraction behaviour
If a code sample doesn't start with a `package ...` statement, the `.scala` generated file wraps this code in a `trait` with a unique name.
Considering a documentation as following.
This is a markdown documentation with a code sample.
```scala
val foo = List("Bar", "Lorem", "Ipsum")
```
The code in the generated file will be:
```scala
package samplesY
trait SampleX {
// File '/path/to/the/file.md', line N
val foo = List("Bar", "Lorem", "Ipsum")
}
```
All the code samples without a `package` in the same documentation files are also gather in a same generated package, `samplesY` in the previous example.
It allows to share some definitions accross the code samples of a documentation file.
This is how to create a value:
```scala
val value = createIt()
```
Then you can use it.
```scala
value.foo()
```
## Build
This is built using SBT.
sbt '^ publishLocal'
[](https://travis-ci.org/cchantep/sbt-hl-compiler)