search

fsprojects / FSharp.Formatting

F# tools for generating documentation (Markdown processor and F# code formatter)
https://fsprojects.github.io/FSharp.Formatting/
Other
464 stars 156 forks source link

Can't generate docs on Linux or OSX #188

Closed icorderi closed 9 years ago

icorderi commented 10 years ago

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

@tpetricek suggested to bring the issue over here.

tpetricek commented 10 years ago

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 commented 10 years ago

A quick search on .net templating yielded:

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 commented 10 years ago

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

haf commented 10 years ago

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 commented 10 years ago

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

haf commented 10 years ago

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

7sharp9 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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

Note that I have included 22e78ef4da15dbe542aa3c4fdf82f79db969f49d 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 commented 9 years ago

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

matthid commented 9 years ago

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 commented 9 years ago

@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 commented 9 years ago

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

tgjones commented 9 years ago

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 commented 9 years ago

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

matthid commented 9 years ago

@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 commented 9 years ago

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 commented 9 years ago

Well done!

icorderi commented 9 years ago

Yay! Great work @matthid!