diff options
author | David Gregory <DavidGregory084@users.noreply.github.com> | 2018-10-31 20:44:53 +0000 |
---|---|---|
committer | Tobias Roeser <le.petit.fou@web.de> | 2018-10-31 21:44:52 +0100 |
commit | 7b4ced648ecd9b79b3a16d67552f0bb69f4dd543 (patch) | |
tree | 2067f545668e03605fb1704ab8286cccb152f6cf /docs/pages | |
parent | 099fdb8defb7d2c8316da94d749c0c23088e0dc9 (diff) | |
download | mill-7b4ced648ecd9b79b3a16d67552f0bb69f4dd543.tar.gz mill-7b4ced648ecd9b79b3a16d67552f0bb69f4dd543.tar.bz2 mill-7b4ced648ecd9b79b3a16d67552f0bb69f4dd543.zip |
Add tut contrib module (#464)
* Add tut contrib module
* Add TutModule tests and documentation
* Use Path instead of PathRef for tut target directory
* Use the correct scala version in TutModule
* Ensure resolving tut doesn't bring in extra scala-library jars
* Ensure MILL_VERSION system property is set in tut tests
* Fork to run tut to fix classpath problems, add test with library usage
* Follow convention w.r.t. publishVersion in testArgs
* Add Scaladoc to TutModule
* Don't supply a default version of Tut
* Update docs to account for mandatory tutVersion setting
* Inline tutArgs, otherwise Tut does not recompile when sources change
Diffstat (limited to 'docs/pages')
-rw-r--r-- | docs/pages/9 - Contrib Modules.md | 56 |
1 files changed, 56 insertions, 0 deletions
diff --git a/docs/pages/9 - Contrib Modules.md b/docs/pages/9 - Contrib Modules.md index 4ddf097a..cd02f2c2 100644 --- a/docs/pages/9 - Contrib Modules.md +++ b/docs/pages/9 - Contrib Modules.md @@ -95,6 +95,62 @@ object project extends ScalaModule { } ``` +### Tut + +This module allows [Tut](https://tpolecat.github.io/tut) to be used in Mill builds. Tut is a documentation tool which compiles and evaluates Scala code in documentation files and provides various options for configuring how the results will be displayed in the compiled documentation. + +To declare a module that uses Tut you can extend the `mill.contrib.tut.TutModule` trait when defining your module. + +This creates a Scala module which compiles markdown, HTML and `.txt` files in the `tut` folder of the module with Tut. + +By default the resulting documents are simply placed in the Mill build output folder but they can be placed elsewhere by overriding the `tutTargetDirectory` task. + +```scala +// build.sc +import mill._, scalalib._, contrib.tut.__ + +object example extends TutModule { + def scalaVersion = "2.12.6" + def tutVersion = "0.6.7" +} +``` + +This defines a project with the following layout: + +``` +build.sc +example/ + src/ + tut/ + resources/ +``` + +In order to compile documentation we can execute the `tut` task in the module: + +``` +sh> mill example.tut +``` + +#### Configuration options + +* tutSourceDirectory - This task determines where documentation files must be placed in order to be compiled with Tut. By default this is the `tut` folder at the root of the module. + +* tutTargetDirectory - A task which determines where the compiled documentation files will be placed. By default this is simply the Mill build's output folder for the `tutTargetDirectory` task but this can be reconfigured so that documentation goes to the root of the module (e.g. `millSourcePath`) or to a dedicated folder (e.g. `millSourcePath / 'docs`) + +* tutClasspath - A task which determines what classpath is used when compiling documentation. By default this is configured to use the same inputs as the `runClasspath`, except for using `tutIvyDeps` rather than the module's `ivyDeps`. + +* tutScalacPluginIvyDeps - A task which determines the scalac plugins which will be used when compiling code examples with Tut. The default is to use the `scalacPluginIvyDeps` for the module. + +* tutNameFilter - A `scala.util.matching.Regex` task which will be used to determine which files should be compiled with tut. The default pattern is as follows: `.*\.(md|markdown|txt|htm|html)`. + +* tutScalacOptions - The scalac options which will be used when compiling code examples with Tut. The default is to use the `scalacOptions` for the module but filtering out options which are problematic in the REPL, e.g. `-Xfatal-warnings`, `-Ywarn-unused-imports`. + +* tutVersion - The version of Tut to use. + +* tutIvyDeps - A task which determines how to fetch the Tut jar file and all of the dependencies required to compile documentation for the module and returns the resulting files. + +* tutPluginJars - A task which performs the dependency resolution for the scalac plugins to be used with Tut. + ### Twirl Twirl templates support. |