This page is no longer maintained — Please continue to the home page at www.scala-lang.org

Scaladoc: Separate HTML from Scala code

7 replies
Kato Kazuyoshi
Joined: 2010-10-22,
User offline. Last seen 29 weeks 1 day ago.

Hi, I want to hear opinions before I merge into SVN trunk.

In Scaladoc, many HTML written inside Scala code. But it's hard to maintain.
Then I implemented a small "template engine" and extracted HTML from Scala code.

You can see my branch at GitHub.
https://github.com/kzys/scala/commits/template

These changes will introduce an ability of "theme" feature. You can insert
your company's logo, custom CSS and so on.

Regards,

Simon Ochsenreither
Joined: 2011-07-17,
User offline. Last seen 42 years 45 weeks ago.
Aw: Scaladoc: Separate HTML from Scala code
While the current approach is pretty messy, I like it because it is unbelievable simple to debug a HTML/CSS problem by looking at some attribute in the HTML source and then searching for it in the IDE.
But I have nothing against the idea of separating the xml stuff a bit ...
Kato Kazuyoshi
Joined: 2010-10-22,
User offline. Last seen 29 weeks 1 day ago.
Re: Aw: Scaladoc: Separate HTML from Scala code

Now I've added template.html on my branch.
https://github.com/kzys/scala/commit/bf8ce59bd814d9e91c95ab22e19f0bc25d2...

On Sun, Sep 4, 2011 at 2:58 AM, Simon Ochsenreither
wrote:
> While the current approach is pretty messy, I like it because it is
> unbelievable simple to debug a HTML/CSS problem by looking at some attribute
> in the HTML source and then searching for it in the IDE.
> But I have nothing against the idea of separating the xml stuff a bit ...
>

Thanks. I want to keep simplicity as much as I can. My template engine is
really small and logic-less. It will open up the door for designers to
contribute Scaladoc.

extempore
Joined: 2008-12-17,
User offline. Last seen 35 weeks 3 days ago.
Re: Scaladoc: Separate HTML from Scala code

On 9/3/11 9:21 AM, Kato Kazuyoshi wrote:
> In Scaladoc, many HTML written inside Scala code. But it's hard to maintain.
> Then I implemented a small "template engine" and extracted HTML from Scala code.
>
> You can see my branch at GitHub.
> https://github.com/kzys/scala/commits/template

Can anyone comment on what best practices have emerged in general
regarding how one cleanly separates code from markup? The last time I
was working in that medium directly was the 1990s, where we used PHP and
java servlets, and what I do remember is that there were big tradeoffs
being made whatever direction we moved.

This is a language agnostic question.

Regarding your changes, and having already admitted with the foregoing
that I'm no authority, this sort of thing:

+ engine.render(Map(
+ "icon" -> icon,
+ "owner" -> owner,
+ "displayName" -> displayName,
+ "order" -> order,
+ "ancestors" -> ancestors,
+ "constructors" -> constructorsElem,
+ "types" -> types,
+ "abstructValues" -> abstructValues,
+ "concreteValues" -> concreteValues,
+ "deprecatedValues" -> deprecatedValues,
+ "comment" -> memberToCommentHtml(tpl, true)
+ ))

is exactly how I'd imagine going about things, so it looks good to me.
Although I think I'd define it like:

def render(pairs: (String, Any)*)

so I didn't have to throw around Map all the time.

Kato Kazuyoshi
Joined: 2010-10-22,
User offline. Last seen 29 weeks 1 day ago.
Re: Scaladoc: Separate HTML from Scala code

On Tue, Sep 6, 2011 at 3:48 AM, Paul Phillips wrote:
> On 9/3/11 9:21 AM, Kato Kazuyoshi wrote:
>>
>> In Scaladoc, many HTML written inside Scala code. But it's hard to
>> maintain.
>> Then I implemented a small "template engine" and extracted HTML from Scala
>> code.
>>
>> You can see my branch at GitHub.
>> https://github.com/kzys/scala/commits/template
>
> Can anyone comment on what best practices have emerged in general regarding
> how one cleanly separates code from markup? The last time I was working in
> that medium directly was the 1990s, where we used PHP and java servlets, and
> what I do remember is that there were big tradeoffs being made whatever
> direction we moved.
>
> This is a language agnostic question.
>

Well, I've been working on the medium since 2008. I think we have some
choices on how to implement/design a template engine.

1. Simple eval style like Scalate SSP or Play Scala.
2. Introduce a mini language like Liquid
3. Logic-less like Mustache

So I chose 3 because it was easy and I didn't want to design yet another
mini language. But probably we can choose 1 too.

> Regarding your changes, and having already admitted with the foregoing that
> I'm no authority, this sort of thing:
>
> +    engine.render(Map(
> +      "icon" -> icon,
> +      "owner" -> owner,
> +      "displayName" -> displayName,
> +      "order" -> order,
> +      "ancestors" -> ancestors,
> +      "constructors" -> constructorsElem,
> +      "types" -> types,
> +      "abstructValues" -> abstructValues,
> +      "concreteValues" -> concreteValues,
> +      "deprecatedValues" -> deprecatedValues,
> +      "comment" -> memberToCommentHtml(tpl, true)
> +    ))
>
> is exactly how I'd imagine going about things, so it looks good to me.
> Although I think I'd define it like:
>
>  def render(pairs: (String, Any)*)
>
> so I didn't have to throw around Map all the time.
>

Thanks, I will follow your advice.

Kato Kazuyoshi
Joined: 2010-10-22,
User offline. Last seen 29 weeks 1 day ago.
Re: Scaladoc: Separate HTML from Scala code

Any comments? I'm going to merge into trunk tomorrow.

On Tue, Sep 6, 2011 at 10:02 AM, Kato Kazuyoshi
wrote:
> On Tue, Sep 6, 2011 at 3:48 AM, Paul Phillips wrote:
>> On 9/3/11 9:21 AM, Kato Kazuyoshi wrote:
>>>
>>> In Scaladoc, many HTML written inside Scala code. But it's hard to
>>> maintain.
>>> Then I implemented a small "template engine" and extracted HTML from Scala
>>> code.
>>>
>>> You can see my branch at GitHub.
>>> https://github.com/kzys/scala/commits/template
>>
>> Can anyone comment on what best practices have emerged in general regarding
>> how one cleanly separates code from markup? The last time I was working in
>> that medium directly was the 1990s, where we used PHP and java servlets, and
>> what I do remember is that there were big tradeoffs being made whatever
>> direction we moved.
>>
>> This is a language agnostic question.
>>
>
> Well, I've been working on the medium since 2008. I think we have some
> choices on how to implement/design a template engine.
>
> 1. Simple eval style like Scalate SSP or Play Scala.
> 2. Introduce a mini language like Liquid
> 3. Logic-less like Mustache
>
> So I chose 3 because it was easy and I didn't want to design yet another
> mini language. But probably we can choose 1 too.
>
>> Regarding your changes, and having already admitted with the foregoing that
>> I'm no authority, this sort of thing:
>>
>> +    engine.render(Map(
>> +      "icon" -> icon,
>> +      "owner" -> owner,
>> +      "displayName" -> displayName,
>> +      "order" -> order,
>> +      "ancestors" -> ancestors,
>> +      "constructors" -> constructorsElem,
>> +      "types" -> types,
>> +      "abstructValues" -> abstructValues,
>> +      "concreteValues" -> concreteValues,
>> +      "deprecatedValues" -> deprecatedValues,
>> +      "comment" -> memberToCommentHtml(tpl, true)
>> +    ))
>>
>> is exactly how I'd imagine going about things, so it looks good to me.
>> Although I think I'd define it like:
>>
>>  def render(pairs: (String, Any)*)
>>
>> so I didn't have to throw around Map all the time.
>>
>
> Thanks, I will follow your advice.
>
> --
> Kato Kazuyoshi
>

vlad.ureche
Joined: 2011-03-17,
User offline. Last seen 1 year 26 weeks ago.
Re: Scaladoc: Separate HTML from Scala code


On Fri, Sep 9, 2011 at 2:40 AM, Kato Kazuyoshi <kato [dot] kazuyoshi [at] gmail [dot] com> wrote:
Any comments? I'm going to merge into trunk tomorrow.


Hi Kato,

Thanks for all the work you put into templates! I think it should definitely go in. :)

There's just one thing that's worth doing before you push into trunk: Could you add a scaladoc testcase that diffs the html pages generated against a reference? That would protect us from accidentally breaking things outside the scope of our commit -- for example templates should generate the exact same output -- you probably verified that by hand, but we should automate it. And this will also be useful in the future, to make sure no change produces unforeseen side effects.

For the check we could use a small but comprehensive example: 2-3 classes, packages, type bounds, manifests, existential types, implicits, links, tags, use cases, package objects for the check. -- the more features tested the better :)

What do you think?


Vlad
Kato Kazuyoshi
Joined: 2010-10-22,
User offline. Last seen 29 weeks 1 day ago.
Re: Scaladoc: Separate HTML from Scala code

On Sat, Sep 10, 2011 at 2:08 AM, Vlad Ureche wrote:
>
> Hi Kato,
>
> Thanks for all the work you put into templates! I think it should definitely
> go in. :)
>
> There's just one thing that's worth doing before you push into trunk: Could
> you add a scaladoc testcase that diffs the html pages generated against a
> reference? That would protect us from accidentally breaking things outside
> the scope of our commit -- for example templates should generate the exact
> same output -- you probably verified that by hand, but we should automate
> it. And this will also be useful in the future, to make sure no change
> produces unforeseen side effects.
>
> For the check we could use a small but comprehensive example: 2-3 classes,
> packages, type bounds, manifests, existential types, implicits, links, tags,
> use cases, package objects for the check. -- the more features tested the
> better :)
>
> What do you think?
>

Thank you. I will add more tests before merge my branch.

Scaladoc had some tests already so I used it for verify my modification.
But the coverage is not so high. I think it's good time to write
comprehensive tests.

Copyright © 2012 École Polytechnique Fédérale de Lausanne (EPFL), Lausanne, Switzerland