How do I add source links in my scaladoc?

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.

On Jan 16, 2012 9:40 PM, "Scott Morrison" <scott.morrison@gmail.com> wrote:

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

On Mon, Jan 16, 2012 at 9:57 PM, Chris Twiner <chris.twiner@gmail.com> wrote:

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.

On Jan 16, 2012 9:40 PM, "Scott Morrison" <scott.morrison@gmail.com> wrote:

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

On Mon, Jan 16, 2012 at 11:18 PM, Jason Zaugg wrote:
> On Mon, Jan 16, 2012 at 9:57 PM, Chris Twiner
> wrote:
>>
>> 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.
>>
>> On Jan 16, 2012 9:40 PM, "Scott Morrison"
>> wrote:
>>>
>>> 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

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

On Mon, Jan 16, 2012 at 11:39 PM, Chris Twiner wrote:
> On Mon, Jan 16, 2012 at 11:18 PM, Jason Zaugg wrote:
>> On Mon, Jan 16, 2012 at 9:57 PM, Chris Twiner
>> wrote:
>>>
>>> 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.
>>>
>>> On Jan 16, 2012 9:40 PM, "Scott Morrison"
>>> wrote:
>>>>
>>>> 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
>
> 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/FullDocP...

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.