Can't generate docs on Linux or OSX

[icorderi]

This is a continuation of Issue #65 from the scaffolding project.

@tpetricek suggested to bring the issue over here.

[tpetricek]

Thanks! Do you have any suggestions for existing cross-platform open-source templating engines that we could use instead of Razor? If we can start by putting together a list of options, that would be great.

[icorderi]

A quick search on .net templating yielded:

• DotLiquid
• nvelocity
• And the current RazorEngine

Not sure if either of them is really cross-platform.
Any chance we can change the bits on Razor to fix this? @7sharp9 mentioned something about it.
There is also the option of FSRazor by @dahlbyk.

[haf]

Some input: DotLiquid works on mono just fine. I'm also eager to get this project working.

[haf]

Also have a look at what Nancy is using, e.g. the markdown engine: https://github.com/NancyFx/Nancy/tree/master/src/Nancy.ViewEngines.Markdown

[haf]

Here's another https://code.google.com/p/nhaml/

[haf]

If I were to choose, I'd spike both DotLiquid and Markdown and then choose one of them,

[7sharp9]

I played about with nhaml, I think it kind of fits F# quite nice.

On 13 Sep 2014, at 16:26, Henrik Feldt notifications@github.com wrote:

If I were to choose, I'd spike both DotLiquid and Markdown and then choose one of them,

—
Reply to this email directly or view it on GitHub.

[tpetricek]

As far as I can tell, NHaml has not been updated in over a year, so DotLiquid sounds like a better choice - if we can put together a PR that replaces RazorEngine with DotLiquid, then I'd be more than happy to merge it!

The only tricky thing in the templates is done here: https://github.com/tpetricek/FSharp.Formatting/blob/master/misc/templates/reference/module.cshtml#L19

I suppose we won't be able to do it in the same way. But we can change the MatadataFormat library, so that it exploses the members as already grouped (and then we don't have to do ad-hoc grouping in the template).

[matthid]

I would vote for fixing/improving RazorEngine (see #202, for a hack to make it work) because:

• Should in theory be very fast.
• Syntax is known to .NET developers.
• Extendible in a lot of directions (see suggestions in Bundle RazorEngine.dll which works on mono #203).
• Very nice to work with from a developers perspective.

Note that I have included 22e78ef to improve the error messages, this should make it a lot easier to fix any remaining problems for now. If there are still problems (with the mentioned hack) I could try to give some pointers in how to solve them as I have a working setup on linux/mono.

[tpetricek]

OK - so I'll finally have some time to get back to this!

• @matthid I see you did some work to improve RazorEngine and also fix how it is used in F# Formatting. Can you send a brief status update on that? What is needed to make it work on Mono? (Also, last time I checked, the newest version required .NET 4.5 while F# Formatting works also on 4.0).
• The alternative would be to use DotLiquid (cc @tgjones), which is more basic (perhaps a minus point, perhaps not so much), but makes the dependencies a bit smaller (a plus point). This is perhaps more work (to change F# Formatting & update projects using it), but it might make some people & projects happy (like @7sharp9 for FsBlog).

[matthid]

I can only speak for RazorEngine:
We are working on a 3.5.0 release which will improve/add APIs to make it work on mono (3.5.0). The nuget package will also be compatible with net40 again. So that should fit your needs. The future will be bright with Razor4 and Roslyn which should improve the mono support and the performance even more (both are open source btw.). I'm personally working on F# support within Razor-templates but that proved to be very difficult and the FCS APIs are not fun to work with... So that will be very far away in the future (If ever finished at all).

I basically have the pull request ready to update RazorEngine within FSharp.Formatting (very few changes to improve mono support), but of course the new version is not released jet. In fact we already use this updated version within RazorEngine to make it work on mono.

Razor templates would make FSharp.Formatting a lot more extendible for users imho (as they can write real code within the templates).

PS: To take advantage of Razor4 and Roslyn you need to update to net45 (both are still beta right now).
Disclaimer: Of course I'm a bit biased towards RazorEngine :)

[tpetricek]

@matthid Thanks for the reply - do you have any timeline for the 3.5.0 release?

Overall, you did a lot of work to make F# Formatting work well with RazorEngine and if we can make it work with NuGet package on Mono, then I'd say we have all we need. So I'd be happy to keep using RazorEngine (thanks for the hard work on making this better!)

I'm still open to supporting DotLiquid, but (if someone wants to do that), it might make more sense to have it as an additional option.

[matthid]

Sadly I have no timeline, however I hope to get a beta nuget package out pretty soon (that would help right?).

[tgjones]

Hello all! It's nice to see interest in using DotLiquid for such a cool project :) Unfortunately I don't currently have time to work on that integration myself, but I'm happy to be "around" to answer any questions that arise if somebody does work on that.

Looking at the existing templates, it looks like most of them would be fairly straightforward to port to DotLiquid. Where it isn't possible, Drop classes can help by moving any complex logic to C#.

For the purposes of open-ness, I should mention that I'm stepping back a little from the DotLiquid project. But it's already stable, works well (in my opinion!), and there are several contributors who are going to help move it forwards.

[haf]

@matthid also relevant: SuaveIO/suave#141 -- or we can go down the same route with dotliquid.

[matthid]

@haf I think the main problem with RazorEngine is lacking documentation not missing features (I tried to improve that a bit in the mean time).

[tpetricek]

Thanks to all the recent amazing work by @matthid, F# Formatting can certainly be used on Mono now. There are still a few tricks, but the latest ProjectScaffold does work fine - so I'm finally closing this. Thanks @matthid!

[haf]

Well done!

[icorderi]

Yay! Great work @matthid!