From dbab980783ce676f59f616ad815e237ec417d12e Mon Sep 17 00:00:00 2001 From: "Aaron S. Hawley" Date: Fri, 7 Jun 2019 08:50:51 -0400 Subject: [PATCH 1/3] Add generating Scaladoc --- _overviews/scaladoc/generate.md | 55 +++++++++++++++++++++++++++++++++ _overviews/scaladoc/overview.md | 5 +-- 2 files changed, 58 insertions(+), 2 deletions(-) create mode 100644 _overviews/scaladoc/generate.md diff --git a/_overviews/scaladoc/generate.md b/_overviews/scaladoc/generate.md new file mode 100644 index 0000000000..a57e4cb0cb --- /dev/null +++ b/_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). + +From the sbt console, run Scaladoc by simply running the `doc` task: + + > 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` commmand-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 precedied 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). diff --git a/_overviews/scaladoc/overview.md b/_overviews/scaladoc/overview.md index efe893b729..b31aea8ef5 100644 --- a/_overviews/scaladoc/overview.md +++ b/_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 From 7b46f87893a3267a6eac82fec10ae38526996ea6 Mon Sep 17 00:00:00 2001 From: "Aaron S. Hawley" Date: Sun, 9 Jun 2019 08:55:24 -0400 Subject: [PATCH 2/3] Fix typos and spellings on Scaladoc page --- _overviews/scaladoc/generate.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_overviews/scaladoc/generate.md b/_overviews/scaladoc/generate.md index a57e4cb0cb..d50b19c5b7 100644 --- a/_overviews/scaladoc/generate.md +++ b/_overviews/scaladoc/generate.md @@ -42,7 +42,7 @@ If you use Scala commands directly to start a console with `scala` or compile wi $ 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` commmand-line option: +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 @@ -50,6 +50,6 @@ For more information on the `scaladoc` command and what other command-line optio 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 precedied the development of sbt, but also because it is useful to the Scala development team with studying bug reports for 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). From af88f6563bbe4db334c8c7077bfca0146a8c5b14 Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Sun, 9 Jun 2019 08:59:36 -0400 Subject: [PATCH 3/3] Avoid confusion about sbt on Scaladoc page --- _overviews/scaladoc/generate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_overviews/scaladoc/generate.md b/_overviews/scaladoc/generate.md index d50b19c5b7..4c26f39a08 100644 --- a/_overviews/scaladoc/generate.md +++ b/_overviews/scaladoc/generate.md @@ -21,7 +21,7 @@ There are two ways to generate API documentation in HTML from your Scala code. 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). -From the sbt console, run Scaladoc by simply running the `doc` task: +In the sbt shell, generate Scaladoc by running `doc`: > doc [info] Main Scala API documentation to target/scala-2.12/api...