Lift Documentation Sprint

[Guillaume Massé]

HI all,

I will spend the next two weeks on lift documentation. I tough of pamflet as the documentation frontend.

I'm currently on a port of play's zentask to lift. I was really happy to remove all the scala code in the views :-). Let's see how well this goes.

Any Ideas / Helping hands are really welcome.

Regards,

Guillaume

[Diego Medina]

I look forward to seeing the results and thanks for the contributions!

Diego

> --
> --
> Lift, the simply functional web framework: http://liftweb.net
> Code: http://github.com/lift
> Discussion: http://groups.google.com/group/liftweb
> Stuck? Help us help you:
> https://www.assembla.com/wiki/show/liftweb/Posting_example_code
>
>
>



--
Diego Medina
Lift/Scala Developer
di...@fmpwizard.com
http://www.fmpwizard.com

[Guillaume Massé]

Hi Diego,

I think I will go with a top down approach for the documentation order.

Sitemap >> View >> Snipet, Commet >> Model, Persistance

I'm still not sure about pamflet. I may need more flexibility than some markdown code

[AGYNAMIX Torsten Uhlmann]

Guillaume,

Thanks for your contributions!

May I suggest you take a look at telegr.am, it's a Lift powered service for easy blogging and documentation. You write your pages in Markdown too, fetched off of Github or Dropbox... 

Torsten.

Von meinem iPad gesendet

[David Pollak]

I used Lyx for Simply Lift.  It's very powerful. But it's also non-trivial to learn and there are a lot of pieces parts and make files and such to flexibly publish stuff.

If I were to start a book or documentation project again, I'd go with Markdown and MultiMarkdown.  What parts of Markdown don't offer you the tools/flexibility you're looking for?

Telegram, Simply Beautiful CMS https://telegr.am

Lift, the simply functional web framework http://liftweb.net

Follow me: http://twitter.com/dpp
Blog: http://goodstuff.im

[Richard Dallaway]

+1!

--
Sent from my phone, so may be terse.

[Guillaume Massé]

I David,

I think I will build the site with lift itself. I *look like* it make more sense to have a lift documentation built on lift. I like how SiteMap / surround / embed just works.

I had problems with Markdown for layout in jekyll, but maybe it's just that I was to stupid/tired to understand the documentation -_-.

Guillaume

[David Pollak]

On Sat, Aug 18, 2012 at 11:55 AM, Guillaume Massé <mas...@gmail.com> wrote:

I David,

I think I will build the site with lift itself. I *look like* it make more sense to have a lift documentation built on lift. I like how SiteMap / surround / embed just works.

Glad you like it.

Telegram is built on Hoisted (http://hoisted.org) which is built on Lift and Lift's rendering pipeline. ;-)

[Peter Petersson]

I think choosing Lift is a great idea and as both Torsten and David already suggested using hoisted and Telegr.am would be a good fit as it will provide tons of nice features right out of the box.

best regards
   Peter Petersson

[Guillaume Massé]

Hi Lift,

I'm happy to present a skeleton for the documentation effort: 

http://doc.scalakata.com

In the same spirit of Scala Kata, I want to emphasis on seeing the result ( http://scalakata.com/50141865e4b0ee9926e6257f )

So the documentation will be full of:

html: output and code

scala: runnable and not

It is really simple to display html and scala code:

<div data-lift="CodeInjection?what=/guide-hidden/view/test.html"></div>

<div data-lift="CodeInjection?what=/guide-hidden/view/test.scala"></div>

 

Runnable scala code via iframe / scalakata

Code on GitHub

https://github.com/MasseGuillaume/lift-doc

Ideas on Trello

https://trello.com/board/liftdoc/503189bd24b57f6c55c4bd7d

I hope you like it,

Guillaume

[Diego Medina]

It looks very nice!

[David Pollak]

beautiful

Guillaume

--

--
Lift, the simply functional web framework: http://liftweb.net
Code: http://github.com/lift
Discussion: http://groups.google.com/group/liftweb
Stuck? Help us help you: https://www.assembla.com/wiki/show/liftweb/Posting_example_code
 
 
 

--

Telegram, Simply Beautiful CMS https://telegr.am

Lift, the simply functional web framework http://liftweb.net

[Antonio Salazar Cardozo]

Awesome!

[Mads Hartmann Jensen]

Looks great!

[Андрей Клаус]

really nice and cool, thanks for the work!

2012/8/20 Guillaume Massé <mas...@gmail.com>

Guillaume

--

[Guillaume Massé]

What happen when you put ruby on rails assets with bootstrap and add some ScalaKata ?

Find it out here: http://doc.scalakata.com/snipet

[Richard Dallaway]

Wow - that's looking great.

Guillaume

--

[AGYNAMIX Torsten Uhlmann]

Great effort, thanks!

Here's a tiny correction: "Snipet" should be spelled "Snippet".

Torsten.

-- 

AGYNAMIX(R). Passionate Software.
Inh. Torsten Uhlmann | Buchenweg 5 | 09380 Thalheim
Phone:       +49 3721 273445
Fax:             +49 3721 273446
Mobile:       +49 151 12412427
Web:           http://www.agynamix.de

[Guillaume Massé]

danke schön, yep I caught that shortly after deploying :-). I still have to fix the url.

[David Pollak]

Guillaume,

This is truly an awesome undertaking. http://doc.scalakata.com/snipet is a very, very cool first step.

One of the longer-range goals I have with Telegram is to completely integrate with http://dexy.it  Dexy is just the kind of "make for complex documents that rely on code and data" tool. It's something we can use to run the entire site through to compile code, run code, catch output (you can even fire up a web app can capture a screen-shot of the run app or a screen-shot of an element on the page of the run web app).

I'd really like to get your project integrated with Telegram and Dexy as a demonstration of Telegram and Dexy and as a way to motivate me to write a lot of docs (move most of Simply Lift over to your project).  What do you think?

--

Telegram, Simply Beautiful CMS https://telegr.am

Lift, the simply functional web framework http://liftweb.net

[Guillaume Massé]

I would love you move most of simply lift over this project, but I dont think Telegram and Dexy should be use. Let me make my point:

As I said in a previous post my goal is to make a documentation that is to good to ignore ©Paul Philips

My long term goal is to merge all of them into http://doc.liftweb.net ( simply.liftweb.net, exploring.liftweb.net, demo.liftweb.net, cookbook.liftweb.net, lift wiki )

Lift + ScalaKata

Pros

• Lift
• we all knows how lift work, contributors would have to learn how to use dexy
• lift templating with embed/surround is really powerful
• Static examples you have a lift context you can run code that user can see
  
• <code data-lift="CodeInjection?what=/guide-hidden/snippet/basic.html"></code>
• <code data-lift="CodeInjection?what=/guide-hidden/snippet/BasicCssSelector.scala"></code> 
• This shows the snippet, it can be extracted from the /src/main/scala/.../snippet in a sbt task to avoid duplication of code
• <i data-lift="embed?what=/guide-hidden/snippet/basic"></i> 
• This run the code
• This way you have 0 duplication: one snippet, one html file we reuse
• Dynamic examples 
• some examples are harder to get that's why I created ScalaKata sandbox where you can run the code, change it, rerun it and finally share it.
• • <iframe src="http://www.scalakata.com/50141865e4b0ee9926e6257fz">
•                     <!-- we could fallback on static examples here if we have a 404/500 from ScalaKata -->
•                     <!-- div data-lift="CodeInjection?what=/guide-hidden/mockup/test.scala"></div -->
•                 </iframe>
• Screenshots 
• I dont think we need dexy to run code, catch output or take screenshots since we have static examples we can show right away.
• If we do need them, it can be done using this dsl and a sbt task

Cons

• ScalaKata need some work
• It is not totally secure
• Have some scaling issues
• memory
• free hosting on cloudbees
• Pretty complex code ( lot's of javascript wiring )
• I'm writing test code ( selenium tests )
• If you have any idea on how to improve
• fork fork fork
• Art: Need some aesthetic/designer rework

[David Pollak]

On Tue, Aug 21, 2012 at 10:39 AM, Guillaume Massé <mas...@gmail.com> wrote:

I would love you move most of simply lift over this project, but I dont think Telegram and Dexy should be use.

I don't think you have a full understanding of Telegram and Dexy. Telegram and Dexy are a simple way to orchestrate the complex process of building different web app examples, running them, capturing their output and building documents based on the output. Everything you want to with Lift can be done in the context of compiling and running your Lift apps within Dexy and capturing the results into a documentation site.

I will also be happy to contribute my time and efforts to a Lift documentation project that uses Telegram and Dexy. A project that does not use these technologies will not have a lot of draw for me to participate in.

 

Let me make my point:

As I said in a previous post my goal is to make a documentation that is to good to ignore ©Paul Philips

My long term goal is to merge all of them into http://doc.liftweb.net ( simply.liftweb.net, exploring.liftweb.net, demo.liftweb.net, cookbook.liftweb.net, lift wiki )

Lift + ScalaKata

Pros

• Lift
• we all knows how lift work, contributors would have to learn how to use dexy

No, they would not. Dexy is a build system that compiles and runs various application. All the documentation work could be done in Lift or in Markdown and woven together by Dexy.

In fact, we Telegram and Dexy integration, all someone would have to do is (1) fork the GitHub repo (2) sign up for Telegram and (3) point their Telegram account to the forked repo and each time they made a change or enhancement, the whole thing would be built for them. Then, they do a pull request and the official site would be rebuilt.

Lift committers don't have to learn SBT. We type "liftsh" and the right things happen. We type "publish-local" or "compile" or "test" depending on where we are in the development process. A good build system does not require simple users learn much. In the case of Telegram and Dexy, we'll need to set up the build process in Dexy and commit that to GitHub. Once that's done, contributors simply add examples (Lift, Scala and HTML) and the rest of the publishing the documentation process is taken care of for them.

 

• lift templating with embed/surround is really powerful

As I've said in prior emails, Telegram's templating system *is* Lift. Telegram builds sites with surround, embed, and many other Lift snippets.

 

• Static examples you have a lift context you can run code that user can see
  
• <code data-lift="CodeInjection?what=/guide-hidden/snippet/basic.html"></code>
• <code data-lift="CodeInjection?what=/guide-hidden/snippet/BasicCssSelector.scala"></code> 
• This shows the snippet, it can be extracted from the /src/main/scala/.../snippet in a sbt task to avoid duplication of code

This is great and there's nothing in the Telegram/Dexy system that would change that. 

• <i data-lift="embed?what=/guide-hidden/snippet/basic"></i> 
• This run the code
• This way you have 0 duplication: one snippet, one html file we reuse

Yes. This is *EXACTLY* what Dexy allows one to do. Dexy will do the complex orchestration of build, run examples, capture output, put output into web pages. So this means that Dexy can compile a Lift app, execute that app, browse to a page, capture that page as HTML or PDF, enter information into the form on that page, capture the resulting page, etc.  Dexy can then make the results available to another Lift app that builds the presentation, capture the results of that Lift app as static pages and voila, you've got a static site based on a chain of programatic dependencies.

 

• Dynamic examples 
• some examples are harder to get that's why I created ScalaKata sandbox where you can run the code, change it, rerun it and finally share it.
• • <iframe src="http://www.scalakata.com/50141865e4b0ee9926e6257fz">
•                     <!-- we could fallback on static examples here if we have a 404/500 from ScalaKata -->
•                     <!-- div data-lift="CodeInjection?what=/guide-hidden/mockup/test.scala"></div -->
•                 </iframe>
• Screenshots 
• I dont think we need dexy to run code, catch output or take screenshots since we have static examples we can show right away.

Except we have to run the code at some point. Running the code in Dexy once means we've got a static site... a site someone can put onto their local system and view without an Internet connection (this is why ScalaDocs are available as both online and downloadable documents)

[Guillaume Massé]

Hi David,

Let me thing about it.

I will take some time to study Dexy and Hoisted.

Guillaume

[Naftoli Gugenheim]

On Tue, Aug 21, 2012 at 1:39 PM, Guillaume Massé <mas...@gmail.com> wrote:

Pretty complex code ( lot's of javascript wiring )

I wonder if reactive-web can help...

[Guillaume Massé]

Hi Nag,

this is exactly what I had in mind

I had a different solution: I was thinking to do an sbt task to copy source files in the war package. I dont fully understand yours, this is the result from my investigation:

/reactive-web-demo/ [...] /snippet/DemoPane.scala fetches the scala source

scalaSource = scala.io.Source.fromInputStream(

  getClass.getResourceAsStream("/scala-sources/reactive/web/demo/snippet/" + snippetName + ".scala")

)

I dont understand where you get the /scala-source/* ressource

I did unpacked the war and saw it sits on /WEB-INF/classes/scala-sources

( by the way, it's crazy how tools like http://java.decompiler.free.fr/ can decompile scala classes, 

in my last internship I showed how easy our clients could steal our IP from extracting .jar or .war package if left un-obfuscated )

but I'm clueless about how it got there.

is it from this part of the build ?

// ... /project/Build.scala

    (scalacOptions in (Compile, doc) <++= (baseDirectory).map{ bd =>

      Seq("-sourcepath", bd.getAbsolutePath, "-doc-source-url", "http://github.com/nafg/reactive/tree€{FILE_PATH}.scala")

    }),

I also saw that you have 2 syms links in webapp dir

lrwxr-xr-x   1 guillaume  staff    49 22 Aug 23:29 reactive-core-api -> ../../../../reactive-core/target/scala-2.9.1/api/

lrwxr-xr-x   1 guillaume  staff    48 22 Aug 23:29 reactive-web-api -> ../../../../reactive-web/target/scala-2.9.1/api/

[Naftoli Gugenheim]

scala-sources is also a symlink:

naftoli@naftoli-HP-Pavilion-dv4-Notebook-PC ~/dev/reactive[wip_implicit_page *]$ ls -l reactive-web-demo/src/main/resources/scala-sources

lrwxrwxrwx 1 naftoli naftoli 9 Jul 18 06:18 reactive-web-demo/src/main/resources/scala-sources -> ../scala/

An sbt configuration would be much nicer (same for api docs). If you want to contribute the code, I'll be happy to take a pull request. I'm not sure it's necessary to write a task; it's likely that you can configure an existing setting. I haven't had a chance to look into it unfortunately.

On Thu, Aug 23, 2012 at 1:16 AM, Guillaume Massé <mas...@gmail.com> wrote:

Hi Nag,

this is exactly what I had in mind

I had a different solution: I was thinking to do an sbt task to copy source files in the war package. I dont fully understand yours, this is the result from my investigation:

/reactive-web-demo/ [...] /snippet/DemoPane.scala fetches the scala source

scalaSource = scala.io.Source.fromInputStream(

  getClass.getResourceAsStream("/scala-sources/reactive/web/demo/snippet/" + snippetName + ".scala")

)

I dont understand where you get the /scala-source/* ressource

I did unpacked the war and saw it sits on /WEB-INF/classes/scala-sources

( by the way, it's crazy how tools like http://java.decompiler.free.fr/ can decompile scala classes, 

in my last internship I showed how easy our clients could steal our IP from extracting .jar or .war package if left un-obfuscated )

but I'm clueless about how it got there.

is it from this part of the build ?

// ... /project/Build.scala

    (scalacOptions in (Compile, doc) <++= (baseDirectory).map{ bd =>

      Seq("-sourcepath", bd.getAbsolutePath, "-doc-source-url", "http://github.com/nafg/reactive/tree€{FILE_PATH}.scala")

    }),

That specifies a command-line argument to scaladoc that allows the scaladocs to link to the code on github.

I also saw that you have 2 syms links in webapp dir

lrwxr-xr-x   1 guillaume  staff    49 22 Aug 23:29 reactive-core-api -> ../../../../reactive-core/target/scala-2.9.1/api/

lrwxr-xr-x   1 guillaume  staff    48 22 Aug 23:29 reactive-web-api -> ../../../../reactive-web/target/scala-2.9.1/api/

Again it would be better if this could be sbt configuration, actually in this case even more so, in order to abstract over the scala version. Another annoying thing is that `package-war` fails if `doc` has not been run (although there's another solution for that: make it depend on it).

On Wednesday, August 22, 2012 6:49:41 PM UTC-4, nafg wrote:

On Tue, Aug 21, 2012 at 1:39 PM, Guillaume Massé <mas...@gmail.com> wrote:

Pretty complex code ( lot's of javascript wiring )

I wonder if reactive-web can help...

[Guillaume Massé]

hi naftoli,

it turned out pretty good:

twitter bootstrap integration

http://reactive.masgui.cloudbees.net

refactor buttons to open in new tab

http://reactive.masgui.cloudbees.net/core/EventStream

live demo with code mirror

http://reactive.masgui.cloudbees.net/showdemo/EventStream_EventSource

with flexible layout

http://reactive.masgui.cloudbees.net/showdemo/JsEventStreamDemo

Regards,

Guillaume

[Guillaume Massé]

Hi David,

While I wrote the reactive documentation, I understood why you want to use dexy.

You are right, with no internet access you can't have dynamic content, so you need some way to publish it and dexy is a great tool for that.

I have an elegant solution for the offline version. I think we should host the two version of the site ( under the same url: http://doc.liftweb.com )

Dynamic Version: One with dynamic examples, the way it is right now, using snippets & al.

Static Version: Another with dynamic examples rendered in some static way with dexy, using screenshot & al.

The user go to the url, the dynamic version is displayed and a cache manifest store a static version. If the user goes offline, the browser switch him back to the static version. There is a button to toggle between versions when you are online.

Telegram

point their Telegram account to the forked repo and each time they made a change or enhancement, the whole thing would be built for them

this make the development cycle for documentation to long. In my generation we want result *right now*, it is possible to use hoisted to develop locally ?

I think if we have a dynamic version, it's better just to have a lift application.

Guillaume

[Naftoli Gugenheim]

Hi David, I was speaking with Guillaume about this, and here are some thoughts we discussed.

1. A major part of the appeal of scalakata is how it embeds the scala interpreter so you tweak the example code at and see how your changes affect the output. This would really make for a great learning tool.

2. This leads to the question of how it could run on telegr.am, since if I'm not mistaken telegr.am sites do not contain bytecode, so how could it run the code? I suppose it could be embedded as an iframe, but that might not be so ideal, since they use a lot more resources in the browser.

3. It occurred to me, perhaps telegr.am could get a sort of plugin architecture. For instance, what if some of the snippets that telegr.am already provides, such as Disqus, Google Maps, and Google Analytics, were actually independent github repositories that functioned as a plugin. Then anyone could write a plugin module for telegr.am, and if it's approved it could be made available to all site authors. Perhaps it's comparable to how Project Locker offers a set of Trac modules that you can enable.

4. This would allow the embedded interpreter view to be developed as a plugin, thus enabling us to run a really amazing site on telegr.am.

What do you think of the idea?

[Guillaume Massé]

Hi all,

I'm almost done with lift css transformation & selections

http://doc.scalakata.com/snippet/transformation/lift

@dpp

can you change simply lift license to 

http://creativecommons.org/licenses/by-nc-sa/3.0/

I would like to re-use some parts.

Cheers,

Guillaume

[Ben Phelan]

That is really nice!

[Alexandre Richonnier]

very nice!

my 2 cents:

currently we have a lot of fragmented documentation on several sources: explore lift, simply lift, assembla wiki, blogs ... etc..

each source has its advantages and disadvantages. For example, the assembla wiki has a search function very limited and is not available offline.

and these documents are not tagged for a version of lift, so  we have code for version 2.0, 2.3, 2.5 all well blended.

For example, unit test documentation exists only on assembla wiki, and is not updated, some specs and specs2 fragment details, with no direct functional code.

So, Lift + ScalaKata is good, but from my point of view, it lacks three essential things that without them, will only be a cosmetic improvement:

_ a wiki feature editable by members as assembla wiki or wikipedia

_ a versioning documentation feature to link a documentation version with a particular lift version or branch.

_ a search function in plain text

as a bonus, you can still improve the system:

_ link release notes and all updates or new features with documentation. For now the release notes are a bit obscure, nothing about new features documentation.

_ link documentation with bug tracking system

Best regards,

Alexandre

actually we have a lot of 

[Erik Post]

On Monday, 15 October 2012 19:19:35 UTC+2, Alexandre Richonnier wrote:

very nice!

my 2 cents:

currently we have a lot of fragmented documentation on several sources: explore lift, simply lift, assembla wiki, blogs ... etc..

  

and these documents are not tagged for a version of lift, so  we have code for version 2.0, 2.3, 2.5 all well blended.

I agree. It's great to see all the improvements, but at the same time if you don't already know where it's currently at, the docs can be confusing. Example: the various forms of snippet invocation: <lift:xxx> vs. <div class="lift:xxx"> vs. <div data-lift="xxx">. Another example: the two (?) bind mechanisms: bind vs. #>.

That said, this effort looks quite snazzy!

 

Cheers,

Erik

[Alexandre Richonnier]

a good example is the new sbt documentation site: http://www.scala-sbt.org/release/docs/index.html

_google search engine
_versioned

[Naftoli Gugenheim]

It's now at http://www.scala-sbt.org/ too.

--

[Guillaume Massé]

This is a great site. The design came from akka documentation site.

I'm currently writing about testing and snippets transformation.

I worked on a REST server with Rogue, I will try to add some documentation about that as well :-).

[Alexandre Richonnier]

cool!

Thanks Guillaume.