Play vs Lagom documentation setup

[Ben McCann]

There's a lot of shared code between Play's Reloader and Lagom's Reloader and I wanted to take a stab at making a more reusable library that both could use.

The main thing I'm wondering about is Play's doc server. Lagom doesn't use it and instead uses sbt-lightbend-markdown. Have there been learnings since setting up Play's docs and perhaps there'd be some benefit to having Play use sbt-lightbend-markdown? Or do the two documentation projects have different requirements in some way and it doesn't make sense to converge them?

Thanks,

Ben

[James Roper]

Play's doc server exists, at least in part, because it always has existed. Ever since Play 1, the documentation has been available directly in Play's dev mode, which at least used to be one of the selling points of Play, you had this very tightly integrated system.  Now, do we even mention that the Play docs are available in dev mode?  Does anyone use them?  That's a genuine, not a rhetorical question, which I don't know the answer to.  We've never removed the feature because it is not hard to maintain it - but if it is the thing that gets in the way of combining Lagom and Play dev modes, then perhaps we should consider removing it.

As to why Lagom doesn't serve the docs - there's no reason to.  Lagom is a microservices framework, not a web framework.  Most services you never interact directly with in a browser, they just serve the backend.  It also wouldn't make sense for the Lagom dev mode to serve them from all 20 services that are currently running.  It might make sense for the Lagom gateway to serve them, but that's a completely separate piece of software, it doesn't even use Play, it's just a reverse proxy written in Netty.

Now I'm in two minds about whether the Lagom and Play dev modes should be consolidated.  The question is what value do we stand to gain by consolidating them, and does that value outweigh the cost introduced by the friction it will introduce?  Our original aim was to write Lagom in 3 months (we actually did it in 4), we knew that the Play dev mode had 95% of what we needed, but there were some things here and there that would need to be done differently, and doing these things in Play, and being dependent on a new release of Play to get the changes, would have prevented us from moving as quick as we needed to.  A few months down the track, we added Maven support - Maven support was developed from start to finish in about 3 weeks, docs and all.  Again this required a few changes to the way things were done in dev mode, and shared library would have been a large impediment to getting this done.

On 18 March 2017 at 05:24, Ben McCann <b...@benmccann.com> wrote:

There's a lot of shared code between Play's Reloader and Lagom's Reloader and I wanted to take a stab at making a more reusable library that both could use.

The main thing I'm wondering about is Play's doc server. Lagom doesn't use it and instead uses sbt-lightbend-markdown. Have there been learnings since setting up Play's docs and perhaps there'd be some benefit to having Play use sbt-lightbend-markdown? Or do the two documentation projects have different requirements in some way and it doesn't make sense to converge them?

sbt-lightbend-markdown was originally meant to be Play's documentation support extracted out of Play, so that other projects could use it.  But there's been another effort at Lightbend called paradox, and this has become the standard that Lightbend is trying to move all projects.  Paradox is also an offshoot of Play's documentation support, and hopefully in future both Play and Lagom will move to it.

 

Thanks,

Ben

--

James Roper
Software Engineer

Lightbend – Build reactive apps!
Twitter: @jroper

[Ben McCann]

Answering only for myself, I've never used the docs from Play's dev mode. I actually didn't know until right now that it was available to end users and thought it was only a feature available to Play developers. I'll probably keep Googling the version on playframework.com though as opposed to using the bundled version as it just seems an easier way to navigate.

I agree completely that Lagom made the right choice to focus on getting a working product developed and that it would have been slower to try to share code from the start. One of the reasons I'd like to work on converging them now is that Greg has it on the Play roadmap to add Maven support to Play. It looks fairly doable to copy a lot of Lagom's improvements in that area back to Play at which point there's very little difference remaining between the two. (There's a couple other pretty minor differences, but I've sent PRs already to address those such as making twirl support optional).

It sounds like it'd be preferred to try to move to Paradox, which seems fairly reasonable, so I could take a stab at a PR for that if folks are amenable.

-Ben

--
You received this message because you are subscribed to the Google Groups "Play framework dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to play-framework-dev+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Will Sargent]

I was looking at this previously -- while the documentation server seems like it would be useful in development, it's somewhat less useful in practice, since you can only bring the documentation up if you've got the application in a runnable state.  This can be very frustrating if you're trying to get Play up and working and you run into a compile time problem, for example in assets, templates or routes.

It's also not searchable and doesn't have thumbnails, so if you have internet, you'll use playframework.com in practice.

I honestly don't know if anyone uses /@documentation in practice -- certainly I've never seen anyone file a bug or PRs improving it.  I think Paradox works fine and if you can get a PR up I'm all for it.

--

Will Sargent

Engineer, Lightbend, Inc.

will.s...@lightbend.com

To unsubscribe from this group and stop receiving emails from it, send an email to play-framework-dev+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[James Roper]

On 20 March 2017 at 13:23, Ben McCann <b...@benmccann.com> wrote:

Answering only for myself, I've never used the docs from Play's dev mode. I actually didn't know until right now that it was available to end users and thought it was only a feature available to Play developers. I'll probably keep Googling the version on playframework.com though as opposed to using the bundled version as it just seems an easier way to navigate.

I agree completely that Lagom made the right choice to focus on getting a working product developed and that it would have been slower to try to share code from the start. One of the reasons I'd like to work on converging them now is that Greg has it on the Play roadmap to add Maven support to Play. It looks fairly doable to copy a lot of Lagom's improvements in that area back to Play at which point there's very little difference remaining between the two. (There's a couple other pretty minor differences, but I've sent PRs already to address those such as making twirl support optional).

It sounds like it'd be preferred to try to move to Paradox, which seems fairly reasonable, so I could take a stab at a PR for that if folks are amenable.

Moving to Paradox will require writing a markdown transformer.  Paradox uses a syntax discussed as part of the CommonMark effort for code snippets, and also has a number of other semantically equivalent but syntactically different features to playdoc, like the way it handles navigation (the equivalent of our index.toc lives in the header of Paradox files).  Paradox also doesn't support wiki link syntax. All of these transformations are straight forward, but need to be done carefully and not by a human.  Probably the best bet would be to implement the transformer using pegdown to parse, and then write a custom serializer that serializes back to Markdown. But if that turns out to be impractical, a hacked up regular expression based solution is also feasible.  Whatever we do though, it should be used by both Play and Lagom, we don't want duplicated efforts here.

The first step to moving to Paradox is to implement the same validation that Play and lightbend-markdown currently do in our documentation - Paradox doesn't currently have any validation.  By implementing the validation, we can then have a high level of confidence that the transformations we've done on the docs are correct.  And of course, as we all know, the validation on Play and Lagom's docs catches a lot of errors during development, it would be a massive step backwards if we were to lose this, so this step is required anyway before we migrate.

 

-Ben

On Sun, Mar 19, 2017 at 6:35 PM, James Roper <ja...@lightbend.com> wrote:

Play's doc server exists, at least in part, because it always has existed. Ever since Play 1, the documentation has been available directly in Play's dev mode, which at least used to be one of the selling points of Play, you had this very tightly integrated system.  Now, do we even mention that the Play docs are available in dev mode?  Does anyone use them?  That's a genuine, not a rhetorical question, which I don't know the answer to.  We've never removed the feature because it is not hard to maintain it - but if it is the thing that gets in the way of combining Lagom and Play dev modes, then perhaps we should consider removing it.

As to why Lagom doesn't serve the docs - there's no reason to.  Lagom is a microservices framework, not a web framework.  Most services you never interact directly with in a browser, they just serve the backend.  It also wouldn't make sense for the Lagom dev mode to serve them from all 20 services that are currently running.  It might make sense for the Lagom gateway to serve them, but that's a completely separate piece of software, it doesn't even use Play, it's just a reverse proxy written in Netty.

Now I'm in two minds about whether the Lagom and Play dev modes should be consolidated.  The question is what value do we stand to gain by consolidating them, and does that value outweigh the cost introduced by the friction it will introduce?  Our original aim was to write Lagom in 3 months (we actually did it in 4), we knew that the Play dev mode had 95% of what we needed, but there were some things here and there that would need to be done differently, and doing these things in Play, and being dependent on a new release of Play to get the changes, would have prevented us from moving as quick as we needed to.  A few months down the track, we added Maven support - Maven support was developed from start to finish in about 3 weeks, docs and all.  Again this required a few changes to the way things were done in dev mode, and shared library would have been a large impediment to getting this done.

On 18 March 2017 at 05:24, Ben McCann <b...@benmccann.com> wrote:

There's a lot of shared code between Play's Reloader and Lagom's Reloader and I wanted to take a stab at making a more reusable library that both could use.

The main thing I'm wondering about is Play's doc server. Lagom doesn't use it and instead uses sbt-lightbend-markdown. Have there been learnings since setting up Play's docs and perhaps there'd be some benefit to having Play use sbt-lightbend-markdown? Or do the two documentation projects have different requirements in some way and it doesn't make sense to converge them?

sbt-lightbend-markdown was originally meant to be Play's documentation support extracted out of Play, so that other projects could use it.  But there's been another effort at Lightbend called paradox, and this has become the standard that Lightbend is trying to move all projects.  Paradox is also an offshoot of Play's documentation support, and hopefully in future both Play and Lagom will move to it.

 

Thanks,

Ben

--

James Roper
Software Engineer

Lightbend – Build reactive apps!
Twitter: @jroper

--
You received this message because you are subscribed to the Google Groups "Play framework dev" group.

To unsubscribe from this group and stop receiving emails from it, send an email to play-framework-dev+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Dominik Dorn]

I was a heavy user of the documentation endpoint in play 1.x. 

However, the endpoint got somehow unusable in Play 2.x as it was

not working when I had some kind of error in my application - and that's usually the time I had to look at the documentation. 

I'm still glad that it's bundled with Play, especially when on the train with limited internet connection. 

[Dominik Dorn]

(sorry, didn't see that will already brought that up)

--

Dominik Dorn
http://dominikdorn.com | http://twitter.com/domdorn
XING: https://www.xing.com/profile/Dominik_Dorn
LINKEDIN: http://at.linkedin.com/pub/dominik-dorn/66/b42/bb1/