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.

Post by 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

[Jason Zaugg]

Post by 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.

Post by 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.

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]

Post by Jason Zaugg

Post by 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.

Post by 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.

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
  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")
  }
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

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

[Chris Twiner]

Post by Chris Twiner

Post by Jason Zaugg

Post by 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.

Post by 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.

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
  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")
  }
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

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

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<https://github.com/mslinn/hanuman> 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]

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
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 <http://That happens to be the delimiter used by
scaladoc. Perhaps chosen to avoid escaping difficulties when used from a
shell script, or perhaps as some form of mild of European pride. The option
specifies a URL template, so that each Scaladoc page links to the
corresponding source code. €{FILE_PATH} is replaced by the path to the
source file, relative to -sourcepath.> 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]

Post by Jason Zaugg
  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"
     )
   }
  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?

Post by Mike Slinn
Thanks Jason, that gave me enough information to make this work!
Mike

[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