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.
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.morri...@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.
> 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.morri...@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.
On Mon, Jan 16, 2012 at 11:18 PM, Jason Zaugg <jza...@gmail.com> wrote: > On Mon, Jan 16, 2012 at 9:57 PM, Chris Twiner <chris.twi...@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.morri...@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:
> 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.
On Mon, Jan 16, 2012 at 11:39 PM, Chris Twiner <chris.twi...@gmail.com> wrote: > On Mon, Jan 16, 2012 at 11:18 PM, Jason Zaugg <jza...@gmail.com> wrote: >> On Mon, Jan 16, 2012 at 9:57 PM, Chris Twiner <chris.twi...@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.morri...@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:
>> 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.
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.
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?
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:
> (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]
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:
