Skip to content

Commit 5d9cf7f

Browse files
committed
Add documentation, depersonalize plugin package
1 parent c4721df commit 5d9cf7f

File tree

3 files changed

+35
-2
lines changed

3 files changed

+35
-2
lines changed

README.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# scripted-sbt-sources
2+
3+
scripted-sbt-sources is a sbt plugin for sbt plugins, which enables better modularisation of `scripted` tests to allow for
4+
easier maintenance and clearer presentation of plugin usage examples.
5+
6+
## Motivation
7+
8+
One of the most important goals for plugin developers is making their creations easy to understand and adopt, and to achieve
9+
that the plugin needs not only documentation, but also clear and simple examples. There are at least two ways of
10+
implementing that:
11+
12+
1. Providing `/examples` subdirectory with select projects.
13+
1. Referencing 'scripted' tests as examples.
14+
15+
Problem with `/examples` subdirectory is that the examples must be kept up to date and made sure to remain working, and the
16+
workflow for that is not immediately obvious. This can be solved by just using `scripted` tests as examples, but truly
17+
good tests bring in a lot of test specific noise into the example code, so the part of the test that represents the example
18+
itself becomes less clear. So maybe there is a way to solve these two problems at once - have clear examples and good tests.
19+
20+
## Usage
21+
22+
scripted-sbt-sources adds new configuration file named `.sources` to `scripted` tests. Developers can specify a newline
23+
separated list of directories in `.sources` that will be merged together with `scripted` test directory. Directories are
24+
merged in decreasing priority, meaning that files in `scripted` test directory and sources listed at the top of the
25+
`.sources` list overwrite directories below them. This new merged test directory is placed in `/target` directory and is
26+
used by the `scripted` task to run tests.
27+
28+
See [src/sbt-test/scripted-sources-plugin/basic-plugin-project](src/sbt-test/scripted-sources-plugin/basic-plugin-project)
29+
for example plugin project.
30+
31+
## License
32+
33+
This software is licensed under the MIT license

src/main/scala/me/ptrdom/sbt/scripted/sources/ScriptedSourcesPlugin.scala renamed to src/main/scala/sbt/scripted/sources/ScriptedSourcesPlugin.scala

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
package me.ptrdom.sbt.scripted.sources
1+
package sbt.scripted.sources
22

33
import java.nio.file.Files
44
import java.nio.file.Path

src/sbt-test/scripted-sources-plugin/basic-plugin-project/build.sbt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import me.ptrdom.sbt.scripted.sources.ScriptedSourcesPlugin
1+
import sbt.scripted.sources.ScriptedSourcesPlugin
22

33
ThisBuild / version := "0.1.0-SNAPSHOT"
44

0 commit comments

Comments
 (0)