Merge pull request #1353 from ashawley/scaladoc

Add page on generating Scaladoc

Author: julienrf

_overviews/scaladoc/generate.md

@@ -0,0 +1,55 @@
+---
+layout: multipage-overview
+title: Generating Scaladoc
+
+discourse: true
+
+partof: scaladoc
+overview-name: Scaladoc
+
+num: 4
+
+permalink: /overviews/scaladoc/:title.html
+---
+
+There are two ways to generate API documentation in HTML from your Scala code.  Those options are:
+
+* use sbt to do it,
+* use the scaladoc command-line tool.
+
+## Using sbt
+
+The easiest and most commonly used way to generate API documentation from your Scala code is with the build tool [sbt](https://www.scala-sbt.org).
+
+In the sbt shell, generate Scaladoc by running `doc`:
+
+    > doc
+    [info] Main Scala API documentation to target/scala-2.12/api...
+    [info] model contains 1 documentable templates
+    [info] Main Scala API documentation successful.
+    [success] Total time: 20 s
+
+The HTML documentation will show up in the respective `target/` directory (or directories for builds with multiple projects) that sbt prints to the console output.
+
+For more information on using sbt on your system, see the [download instructions](https://www.scala-lang.org/download/) for [getting started with Scala and sbt on the command line]({{site.baseurl}}/getting-started-sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.html).
+
+For additional information about configuring Scaladoc in sbt, see the [Generate API documentation](https://www.scala-sbt.org/1.x/docs/Howto-Scaladoc.html) section of the sbt reference manual.
+
+## Using scaladoc command
+
+If you use Scala commands directly to start a console with `scala` or compile with `scalac`, then you should have a `scaladoc` command-line utility, as well.  This is a more advanced and less commonly used method of generating Scaladoc.
+
+    $ scaladoc src/main/scala/App.scala
+    model contains 1 documentable templates
+
+This will put the HTML in the current directory.  This is probably not what you want.  It's preferable to output to a subdirectory.   To specify a different target directory, use the `-d` command-line option:
+
+    $ scaladoc -d build/ src/main/scala/App.scala
+
+For more information on the `scaladoc` command and what other command-line options it supports, see the [scaladoc man page](https://www.scala-lang.org/files/archive/nightly/docs/manual/html/scaladoc.html).
+
+This command is harder to operate with more complex projects containing both multiple Scala source files and library dependencies.  This is why using sbt (see above) is easier and better suited for generating Scaladoc.
+
+The Scaladoc command exists because it preceded the development of sbt, but also because it is useful to the Scala development team with studying bug reports for Scaladoc.
+
+More information on directly using the Scala commands, like `scaladoc`, is discussed at [your first lines of Scala](https://www.scala-lang.org/documentation/your-first-lines-of-scala.html).

_overviews/scaladoc/overview.md

@@ -17,10 +17,11 @@ system that lives in the comments of Scala source code and which generates
 documentation related to the code structure within which it is written. It is
 based on other comment based documentation systems like Javadoc.
 
-There are two flavors of Scaladoc documentation:
+There are three aspects of Scaladoc documentation:
 
   - **[Using the Scaladoc interface]({{ site.baseurl }}/overviews/scaladoc/interface.html)** – how to navigate and use generated Scaladoc documentation to learn more about a library.
-  - **[Generating documentation for your library with Scaladoc]({{ site.baseurl }}/overviews/scaladoc/for-library-authors.html)** – how to use Scaladoc to generate documentation for your library.
+  - **[Scaladoc for Library Authors]({{ site.baseurl }}/overviews/scaladoc/for-library-authors.html)** – how to add Scaladoc comments to generate documentation for your library.
+  - **[Generating documentation for your library with Scaladoc]({{ site.baseurl }}/overviews/scaladoc/generate.html)** – how to use Scaladoc to generate documentation for your library.
 
 ### Contributing to Scaladoc