How do I add source links in my scaladoc?

[Scott Morrison]

Could someone point me to a recipe showing me how to have "sbt doc"
produce Scaladoc output that includes a link to sources?

Googling is failing me. I suspect that there is simply an option I can
put in my build.sbt, but the sbt documentation doesn't seem to say
anything about scaladoc.

thanks,
Scott Morrison

[Chris Twiner]

Lol, should have read this one first. I had a plugin for 0.7 but I am only just working on 0.1x now.  I'll chat on the sbt group after I've done it.

Sbt questions are probably better off being asked on the sbt mailing list though.

[Jason Zaugg]

You need a combination of two command line options to the scaladoc tool. First, -doc-source-url provides a URL template, and second -sourcepath establishes the base directory for the project.

I've just added support for this to the Scalaz build [1]

In `standardSettings`, which is shared by *all* projects in that build, I added:

  scalacOptions in (Compile, doc) <++= (baseDirectory in LocalProject("scalaz")).map {

      bd => Seq(

        "-sourcepath", 

        bd.getAbsolutePath, 

        "-doc-source-url", 

        "https://github.com/scalaz/scalaz/tree/scalaz-seven€{FILE_PATH}.scala")

  }

Dissecting this a bit:

1. we're configuring the key `compile:scalac-options(for doc)`. By default, this takes on the value of `compile:scalac-options`.

2. <++= means we need to access the value of other keys to initialize this one, and we are appending a sequence of additional elements to the previous value associated with this key. 

3. `baseDirectory in in LocalProject("scalaz")` refers to the parent project; I have to do it this way rather than simply referring to `baseDirectory in scalaz`, otherwise there would be a circular reference reported by the scala compiler when loading the build definition.

-jason

[1] https://github.com/scalaz/scalaz/blob/scalaz-seven/project/build.scala#L16

[Chris Twiner]

Thats nice, but isn't great for offline viewing, a bulk replace of a
dummy url token fixes that up nicely.

[Chris Twiner]

to fill that out a bit, I've made a partial migration and added
handling of multi-sub projects:

https://github.com/chris-twiner/scalesXml/blob/fullDocs/project/FullDocProject.scala

This approach uses sxr to display hyperlinked code and does a "smart"
replace. Many thanks to Jason for the fullDocs approach itself. The
benefit being that it can be used offline locally and packaged or via
a central website as well.

I have to make it less chatty (turn the content to debug only form
repointSxr) and handle .java files (not just scala ones) - but I'll
get round to that in the next days - I want at least the combined docs
and sxr for the Scales Xml 0.3 release.

[Michael Slinn]

I want links to source in my project. My project only has build.sbt in the top directory. I don't want a whole lot of SBT code, so I just tried the following:

1) Created project/build.scala and put the following in it:

scalacOptions in (Compile, doc) <++= (baseDirectory in LocalProject("hanuman")).map {

  bd => Seq("-sourcepath", bd.getAbsolutePath, 

            "-doc-source-url", "https://github.com/mslinn/hanuman€{FILE_PATH}.scala")

}

(no idea what the Euro symbol in the 3rd line does, just copied it from the example).

2) Ran sbt doc:

$ sbt doc

[info] Loading global plugins from C:\Users\Mike Slinn\.sbt\plugins

[info] Loading project definition from E:\work\hanuman\project

[info] Compiling 1 Scala source to E:\work\hanuman\project\target\scala-2.9.1\sbt-0.11.2\classes...

[error] IO error while decoding E:\work\hanuman\project\build.scala with UTF-8

[error] Please try specifying another one using the -encoding option

[error] one error found

[error] {file:/E:/work/hanuman/project/}default-5e0f21/compile:compile: Compilation failed

Project loading failed: (r)etry, (q)uit, (l)ast, or (i)gnore?

3) I removed the Euro symbol and retried:

$ sbt doc

[info] Loading global plugins from C:\Users\Mike Slinn\.sbt\plugins

[info] Loading project definition from E:\work\hanuman\project

[info] Compiling 1 Scala source to E:\work\hanuman\project\target\scala-2.9.1\sbt-0.11.2\classes...

[error] E:\work\hanuman\project\build.scala:1: expected class or object definition

[error] scalacOptions in (Compile, doc) <++= (baseDirectory in LocalProject(" hanuman ")).map {

[error] ^

[error] one error found

[error] {file:/E:/work/hanuman/project/}default-5e0f21/compile:compile: Compilation failed

Project loading failed: (r)etry, (q)uit, (l)ast, or (i)gnore?

4) I put the code into project/build.sbt instead and got the same error.

Is there a way to do this without getting into a whole lot of code?

Mike

[Jason Zaugg]

On Sun, Mar 4, 2012 at 8:32 PM, Michael Slinn <msl...@gmail.com> wrote:
> I want links to source in my project. My project only has build.sbt in the
> top directory. I don't want a whole lot of SBT code, so I just tried the
> following:
>
> 1) Created project/build.scala and put the following in it:
>
> scalacOptions in (Compile, doc) <++= (baseDirectory in
> LocalProject("hanuman")).map {
>   bd => Seq("-sourcepath", bd.getAbsolutePath,
>             "-doc-source-url",
> "https://github.com/mslinn/hanuman€{FILE_PATH}.scala")
> }
>
> (no idea what the Euro symbol in the 3rd line does, just copied it from the
> example).

Your text editor and your SBT instance disagree [1] on the encoding of
the file. Either add -Dfile.encoding=UTF-8 to your SBT options, or
stick to ASCII and represent \u20AC rather than €. [2]

-jason

[1] https://github.com/scalaz/scalaz/issues/80#issuecomment-4312538
[2] http://www.joelonsoftware.com/articles/Unicode.html

[Michael Slinn]

Retronym clarified the Euro symbol usage. I'm still in the dark about how to generate source links without writing large chunks of SBT code. I had hoped to be able to do something simple, like this, but the "simple build tool" is anything but:

docOptions += "-doc-source-url https://github.com/mslinn/hanuman"

^

E:\work\hanuman\build.sbt:20: error: reassignment to val

Mike

[Jason Zaugg]

[forwarding to list]

On Sun, Mar 4, 2012 at 11:24 PM, Jason Zaugg <jza...@gmail.com> wrote:
> The correct setting is:

>
>   scalacOptions in (Compile, doc) <++= (baseDirectory in

> LocalProject("myRootProject")).map {
>      (bd: File) => Seq[String](

>         "-sourcepath", bd.getAbsolutePath,
>         "-doc-source-url",

> "https://github.com/scalaz/scalaz/tree/scalaz-seven€{FILE_PATH}.scala"
>      )
>    }
>
> If you have a single module project, you could simplify to:
>
>   scalacOptions in (Compile, doc) <++= baseDirectory.map {
>      (bd: File) => Seq[String](

>         "-sourcepath", bd.getAbsolutePath,
>         "-doc-source-url",

> "https://github.com/scalaz/scalaz/tree/scalaz-seven€{FILE_PATH}.scala"
>      )
>    }
>
> -jason

[Mike Slinn]

Thanks Jason, that gave me enough information to make this work!

Mike

[Paul Dao]

Where are the scaladoc html file generated to?

[Mike Slinn]

Since sbt 0.12, when there are only Java sources or only Scala sources but not both, the output directory is target/api/. When there are both Java and Scala sources present, the output directories are target/api/java target/api/scala.

Mike