fix docs

9 files changed, 231 insertions, 69 deletions

diff --git a/core/src/mill/util/Logger.scala b/core/src/mill/util/Logger.scala
index 17c66d27..9b815516 100644
--- a/core/src/mill/util/Logger.scala
+++ b/core/src/mill/util/Logger.scala
@@ -22,8 +22,8 @@ import ammonite.util.Colors
   *
   * Also contains the two forwarded stdout and stderr streams, for code executed
   * by Mill to use directly. Typically these correspond to the stdout and stderr,
-  * but when `--show` is used both are forwarded to stderr and stdout is only
-  * used to display the final `--show` output for easy piping.
+  * but when `show` is used both are forwarded to stderr and stdout is only
+  * used to display the final `show` output for easy piping.
   */
 trait Logger {
   def colored: Boolean
diff --git a/docs/cross.md b/docs/cross.md
index fe14a23e..f92678d5 100644
--- a/docs/cross.md
+++ b/docs/cross.md
@@ -17,12 +17,12 @@ This defines three copies of `FooModule`: `"210"`, `"211"` and `"212"`, each of
 which has their own `suffix` target. You can then run them via
 
 ```bash
-mill --show foo[2.10].suffix
-mill --show foo[2.10].bigSuffix
-mill --show foo[2.11].suffix
-mill --show foo[2.11].bigSuffix
-mill --show foo[2.12].suffix
-mill --show foo[2.12].bigSuffix
+mill show foo[2.10].suffix
+mill show foo[2.10].bigSuffix
+mill show foo[2.11].suffix
+mill show foo[2.11].bigSuffix
+mill show foo[2.12].suffix
+mill show foo[2.12].bigSuffix
 ```
 
 The modules each also have a `millSourcePath` of
@@ -66,13 +66,13 @@ takes two parameters instead of one. This creates the following modules each
 with their own `suffix` target:
 
 ```bash
-mill --show foo[210,jvm].suffix
-mill --show foo[211,jvm].suffix
-mill --show foo[212,jvm].suffix
-mill --show foo[210,js].suffix
-mill --show foo[211,js].suffix
-mill --show foo[212,js].suffix
-mill --show foo[212,native].suffix
+mill show foo[210,jvm].suffix
+mill show foo[211,jvm].suffix
+mill show foo[212,jvm].suffix
+mill show foo[210,js].suffix
+mill show foo[211,js].suffix
+mill show foo[212,js].suffix
+mill show foo[212,native].suffix
 ```
 
 ## Using Cross Modules from Outside
@@ -121,12 +121,12 @@ class BarModule(crossVersion: String) extends Module{
 Here, you can run:
 
 ```bash
-mill --show foo[2.10].suffix
-mill --show foo[2.11].suffix
-mill --show foo[2.12].suffix
-mill --show bar[2.10].bigSuffix
-mill --show bar[2.11].bigSuffix
-mill --show bar[2.12].bigSuffix
+mill show foo[2.10].suffix
+mill show foo[2.11].suffix
+mill show foo[2.12].suffix
+mill show bar[2.10].bigSuffix
+mill show bar[2.11].bigSuffix
+mill show bar[2.12].bigSuffix
 ```
 
 
diff --git a/docs/extending.md b/docs/extending.md
index 9b4656f8..299d8e76 100644
--- a/docs/extending.md
+++ b/docs/extending.md
@@ -148,5 +148,25 @@ builds, simply publish your code as a library to maven central.
 For more information, see Ammonite's
 [Ivy Dependencies documentation](http://ammonite.io/#import$ivy)
 
-## Custom Main Methods
+## Evaluator Commands
 
+You can define a command that takes in the current `Evaluator` as an argument,
+which you can use to inspect the entire build, or run arbitrary tasks. For
+example, here is the `mill.scalalib.GenIdea/idea` command which uses this to
+traverse the module-tree and generate an Intellij project config for your build.
+
+```scala
+def idea(ev: Evaluator[Any]) = T.command{
+  mill.scalalib.GenIdea(
+    implicitly,
+    ev.rootModule,
+    ev.discover
+  )
+}
+```
+
+Many built-in tools are implemented as custom evaluator commands:
+[all](intro.html#all), [describe](intro.html#describe),
+[resolve](intro.html#resolve), [show](intro.html#show). If you want a way to run Mill
+commands and programmatically manipulate the tasks and outputs, you do so with
+your own evaluator command.
diff --git a/docs/index.md b/docs/index.md
index ff26941c..921d4aae 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,3 +1,6 @@
+Mill is your shiny new Scala build tool! Confused by SBT? Frustrated by Maven?
+Perplexed by Gradle? Give Mill a try!
+
 Mill is a general purpose build-tool. It has built in support for the
 [Scala](https://www.scala-lang.org/) programming language, and can serve as a
 replacement for [SBT](http://www.scala-sbt.org/), but can also be extended to
@@ -6,11 +9,11 @@ through external subprocesses.
 
 Mill aims for simplicity by re-using concepts you are already familiar with to
 let you define your project's build. Mill's `build.sc` files are Scala scripts.
-If you think SBT is complicated, give Mill a try!
 
-- [Introduction](/mill/intro)
-- [Extending](/mill/extending)
-- [Tasks](/mill/tasks)
-- [Modules](/mill/modules)
-- [Cross Building](/mill/cross)
-- [Internals](/mill/internals)
\ No newline at end of file
+
+- [Introduction](intro.html)
+- [Extending](extending.html)
+- [Tasks](tasks.html)
+- [Modules](modules.html)
+- [Cross Building](cross.html)
+- [Internals](internals.html)
\ No newline at end of file
diff --git a/docs/intro.md b/docs/intro.md
index 3e3778d5..fc33359b 100644
--- a/docs/intro.md
+++ b/docs/intro.md
@@ -56,18 +56,89 @@ $ mill --watch foo.compile
 $ mill --watch foo.run 
 ```
 
-### Show Target Output
+### Command-line Tools
+
+Mill comes built in with a small number of useful command-line utilities:
+
+#### all
+
+```bash
+mill all foo.{compile,run}
+mill all "foo.{compile,run}"
+mill all foo.compile foo.run
+mill all _.compile # run compile for every top-level module
+mill all __.compile  # run compile for every module
+```
+
+`all` runs multiple tasks in a single command
+
+#### resolve
+
+```bash
+mill resolve foo.{compile,run}
+mill resolve "foo.{compile,run}"
+mill resolve foo.compile foo.run
+mill resolve _.compile          # list the compile tasks for every top-level module
+mill resolve __.compile         # list the compile tasks for every module
+mill resolve _                  # list every top level module or task
+mill resolve foo._              # list every task directly within the foo module
+mill resolve __                 # list every module or task recursively
+mill resolve foo._              # list every task recursively within the foo module
+```
+
+`resolve` lists the tasks that match a particular query, without running them.
+This is useful for "dry running" an `mill all` command to see what would be run
+before you run them, or to explore what modules or tasks are available from the
+command line using `resolve _`, `resolve foo._`, etc.
+
+
+#### describe
+
+```bash
+$ mill describe core.run
+
+core.run(ScalaModule.scala:211)
+Inputs:
+    core.mainClass
+    core.runClasspath
+    core.forkArgs
+    core.forkEnv
+```
+
+`describe` is a more verbose version of [resolve](#resolve). In addition to
+printing out the name of one-or-more tasks, it also display's it's source
+location and a list of input tasks. This is very useful for debugging and
+interactively exploring the structure of your build from the command line.
+
+`describe` also works with the same `_`/`__` wildcard/query syntaxes that
+[all](#all)/[resolve](#resolve) do:
+
+
+```bash
+mill describe foo.compile
+mill describe foo.{compile,run}
+mill describe "foo.{compile,run}"
+mill describe foo.compile foo.run
+mill describe _.compile
+mill describe __.compile
+mill describe _
+mill describe foo._
+mill describe __
+mill describe foo._
+```
+
+#### show
 
 By default, Mill does not print out the metadata from evaluating a task. Most
 people would not be interested in e.g. viewing the metadata related to
 incremental compilation: they just want to compile their code! However, if you
 want to inspect the build to debug problems, you can make Mill show you the
-metadata output for a task using the `--show` flag:
+metadata output for a task using the `show` flag:
 
-You can also ask Mill to display the metadata output of a task using `--show`:
+You can also ask Mill to display the metadata output of a task using `show`:
 
 ```bash
-$ mill --show foo.compile
+$ mill show foo.compile
 {
     "analysisFile": "/Users/lihaoyi/Dropbox/Github/test/out/foo/compile/dest/zinc",
     "classes": {
@@ -79,12 +150,12 @@ $ mill --show foo.compile
 This also applies to tasks which hold simple configurable values:
 
 ```bash
-$ mill --show foo.sources
+$ mill show foo.sources
 [
     {"path": "/Users/lihaoyi/Dropbox/Github/test/foo/src"}
 ]
 
-$ mill --show foo.compileDepClasspath
+$ mill show foo.compileDepClasspath
 [
     {"path": ".../org/scala-lang/scala-compiler/2.12.4/scala-compiler-2.12.4.jar"},
     {"path": ".../org/scala-lang/scala-library/2.12.4/scala-library-2.12.4.jar"},
@@ -93,18 +164,22 @@ $ mill --show foo.compileDepClasspath
 ]
 ```
 
+`show` is also useful for interacting with Mill from external tools, since the
+JSON it outputs is structured and easily parsed & manipulated.
+
+### IntelliJ Support
+
+Mill supports IntelliJ by default. Use `mill mill.scalalib.GenIdea/idea` to
+generate an IntelliJ project config for your build.
+
+This also configures IntelliJ to allow easy navigate & code-completion within
+your build file itself.
+
+
 Any flags passed *before* the name of the task (e.g. `foo.compile`) are given to
 Mill, while any arguments passed *after* the task are given to the task itself.
 For example:
 
-```bash
-$ mill --watch foo.run
-```
-
-Makes Mill watch-and-re-evaluate the `foo.run` task, while `mill foo.run
---watch` evaluates `foo.run` once and passes it the `--watch` flag. This matches
-the behavior of other executables such as `java` or `python`.
-
 ### The Build Repl
 
 ```bash
@@ -430,10 +505,10 @@ first run until it's inputs change (in this case, if someone edits the
 `foo.sources` files which live in `foo/src`. Cached Targets cannot take
 parameters.
 
-You can print the value of your custom target using `--show`, e.g.
+You can print the value of your custom target using `show`, e.g.
 
 ```bash
-mill run --show lineCount
+mill run show lineCount
 ```
 
 You can define new un-cached Commands using the `T.command{...}` syntax. These
@@ -502,8 +577,6 @@ override `compile` and `run` to add additional logging messages.
 
 In Mill builds the `override` keyword is optional.
 
-### Publishing Modules
-
 ## Common Project Layouts
 
 Above, we have shown how to work with the Mill default Scala module layout. Here
@@ -560,10 +633,6 @@ latter of which runs your code on Node.js, which must be pre-installed)
 `ScalaJSModule` also exposes the `foo.fastOpt` and `foo.fullOpt` tasks for
 generating the optimized Javascript file.
 
-### Cross Scala-JVM/Scala.js Modules
-
-### Cross Scala-Version Scala-JVM/JS Modules
-
 ### SBT-Compatible Modules
 
 ```scala
@@ -622,8 +691,69 @@ foo/
             scala-2.12/
 ```
 
-### SBT-Compatible Cross Scala-Version Scala-JVM/JS Modules
+### Publishing
+```scala
+import mill._
+import mill.scalalib._
+object foo extends ScalaModule with PublishModule{
+  def scalaVersion = "2.12.4"
+  def publishVersion = "0.0.1
+  def pomSettings = PomSettings(
+    description = "My first library",
+    organization = "com.lihaoyi",
+    url = "https://github.com/lihaoyi/mill",
+    licenses = Seq(
+      License("MIT license", "http://www.opensource.org/licenses/mit-license.php")
+    ),
+    scm = SCM(
+      "git://github.com/lihaoyi/mill.git",
+      "scm:git://github.com/lihaoyi/mill.git"
+    ),
+    developers = Seq(
+      Developer("lihaoyi", "Li Haoyi","https://github.com/lihaoyi")
+    )
+  )
+}
+```
+
+You can make a module publishable by extending `PublishModule`.
+
+`PublishModule` then needs you to define a `publishVersion` and `pomSettings`.
+The `artifactName` defaults to the name of your module (in this case `foo`) but
+can be overriden. The `organization` is defined in `pomSettings`.
+
+Once you've mixed in `PublishModule`, you can publish your libraries to maven
+central  via:
+
+```bash
+target/bin/mill mill.scalalib.PublishModule/publishAll \
+        lihaoyi:$SONATYPE_PASSWORD \
+        $GPG_PASSWORD \ 
+        foo.publishArtifacts
+```
+
+This uploads them to `oss.sonatype.org` where you can log-in and stage/release
+them manually. You can also pass in the `--release true` flag to perform the
+staging/release automatically:
+
+```bash
+target/bin/mill mill.scalalib.PublishModule/publishAll \
+        lihaoyi:$SONATYPE_PASSWORD \
+        $GPG_PASSWORD \ 
+        foo.publishArtifacts \
+        --release true
+```
 
+If you want to publish/release multiple modules, you can use the `_` or `__`
+wildcard syntax:
+
+```bash
+target/bin/mill mill.scalalib.PublishModule/publishAll \
+        lihaoyi:$SONATYPE_PASSWORD \
+        $GPG_PASSWORD \ 
+        __.publishArtifacts \
+        --release true
+```
 
 
 ## Example Builds
@@ -636,7 +766,8 @@ integration tests and examples:
 
 - [Mill Build](https://github.com/lihaoyi/mill/blob/master/integration/test/resources/acyclic/build.sc#L1)
 
-A small single-module cross-build, with few sources minimal dependencies
+A small single-module cross-build, with few sources minimal dependencies, and
+wired up for publishing to Maven Central
 
 
 ### Better-Files
diff --git a/docs/modules.md b/docs/modules.md
index 8bbe6d49..c4dd3f8b 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -19,7 +19,7 @@ object foo extends mill.Module{
 ```
 
 You would be able to run the two targets via `mill foo.bar` or `mill
-foo.baz.qux`. You can use `mill --show foo.bar` or `mill --show foo.baz.qux` to
+foo.baz.qux`. You can use `mill show foo.bar` or `mill show foo.baz.qux` to
 make Mill echo out the string value being returned by each Target. The two
 targets will store their output metadata & files at `./out/foo/bar` and
 `./out/foo/baz/qux` respectively.
@@ -46,11 +46,11 @@ object foo2 extends FooModule{
 
 This would make the following targets available from the command line
 
-- `mill --show foo1.bar`
-- `mill --show foo1.baz`
-- `mill --show foo2.bar`
-- `mill --show foo2.baz`
-- `mill --show foo2.qux`
+- `mill show foo1.bar`
+- `mill show foo1.baz`
+- `mill show foo2.bar`
+- `mill show foo2.baz`
+- `mill show foo2.qux`
 
 The built in `mill.scalalib` package uses this to define
 `mill.scalalib.ScalaModule`, `mill.scalalib.SbtModule` and
diff --git a/docs/publishing.md b/docs/publishing.md
deleted file mode 100644
index e69de29b..00000000
--- a/docs/publishing.md
+++ /dev/null
diff --git a/main/src/mill/main/ReplApplyHandler.scala b/main/src/mill/main/ReplApplyHandler.scala
index 76ef354f..eac0c7f0 100644
--- a/main/src/mill/main/ReplApplyHandler.scala
+++ b/main/src/mill/main/ReplApplyHandler.scala
@@ -78,8 +78,8 @@ object ReplApplyHandler{
     }
     pprint.Tree.Lazy(ctx =>
       Iterator(
-        t.toString, "(", t.ctx.fileName, ":", t.ctx.lineNum.toString, ")",
-        t.ctx.lineNum.toString, "\n", ctx.applyPrefixColor("Inputs:").toString
+        t.toString, "(", t.ctx.fileName.split('/').last, ":", t.ctx.lineNum.toString, ")",
+        "\n", ctx.applyPrefixColor("Inputs:").toString
       ) ++ t.inputs.iterator.flatMap(rec).map("\n    " + _.render)
     )
   }
diff --git a/readme.md b/readme.md
index 4dc6ca1c..ad142d5e 100644
--- a/readme.md
+++ b/readme.md
@@ -8,7 +8,15 @@
 [patreon-badge]: https://img.shields.io/badge/patreon-sponsor-ff69b4.svg
 [patreon-link]: https://www.patreon.com/lihaoyi
 
-Your shiny new Scala build tool!
+Your shiny new Scala build tool! Confused by SBT? Frustrated by Maven? Perplexed
+by Gradle? Give Mill a try!
+
+If you want to use Mill in your own projects, check out our documentation:
+
+- [Documentation](http://www.lihaoyi.com/mill/)
+
+The remainder of this readme is targeted at people who wish to work on Mill's
+own codebase.
 
 ## How to build and test
 
@@ -42,13 +50,13 @@ There is already a `watch` option that looks for changes on files, e.g.:
 ```
 
 You can get Mill to show the JSON-structured output for a particular `Target` or
-`Command` using the `--show` flag:
+`Command` using the `show` flag:
 
 ```bash
-./target/bin/mill --show core.scalaVersion
-./target/bin/mill --show core.compile
-./target/bin/mill --show core.assemblyClasspath
-./target/bin/mill --show core.test
+./target/bin/mill show core.scalaVersion
+./target/bin/mill show core.compile
+./target/bin/mill show core.assemblyClasspath
+./target/bin/mill show core.test
 ```
 
 Output will be generated into a the `./out` folder.
@@ -120,7 +128,7 @@ will run `compile` and `test` targets in `scalalib` module.
 
 * Run multiple targets in multiple modules:
 ```bash
-mill --show --all {core,scalalib}.{scalaVersion,scalaBinaryVersion}
+mill show --all {core,scalalib}.{scalaVersion,scalaBinaryVersion}
 ```
 
 will run `scalaVersion` and `scalaBinaryVersion` targets in both `core` and `scalalib` modules. 
@@ -293,7 +301,7 @@ Each folder currently contains the following files:
   console during evaluation.
 
 - `meta.json`: the cache-key and JSON-serialized return-value of the
-  `Target`/`Command`. The return-value can also be retrieved via `mill --show
+  `Target`/`Command`. The return-value can also be retrieved via `mill show
   core.compile`. Binary blobs are typically not included in `meta.json`, and
   instead stored as separate binary files in `dest/` which are then referenced
   by `meta.json` via `PathRef`s