Api docs

[haf]

Not ready to merge. Complains about F# version 4.3 expected 4.3.1. Continuation of #225

@dsyme or @tpetricek Can you take it from here?

/cc @matthid

[dsyme]

It would be great to have the documentation generation in place.

I managed to run generate.fsx from this PR on Windows without error but there's definitely more work needed as index.md is not yet under "content" to generate HTML.

I know I've mentioned this before, but I do wonder if it might be possible to change to FAKE. It's such a standard in the F# community projects, and would be a great fit for Suave. I've always had real trouble running ruby build scripts on Windows, but maybe that's just me, but FAKE works really well cross-platform.

[ademar]

👍

[haf]

My three killer features that I want from FAKE are these:

• not having to duplicate all dependencies inside the build file - that's already declared in paket.references and/or throughout the fsproj files.
• paket pack support with docs on how to do it, currently missing
• tag, push to git, push to nuget -- and if a tag exists, a push fails, roll back the push (basically ./build.fsx release)

My experience with FAKE so far has been incredibly painful. For albacore I spend 15 minutes installing ruby (once per machine per year, normally) and then it does it all for me. For FAKE I've spent hours (on other projects like Http.fs) just trying to make it do my bidding around nuget creation. Obviously this is skewed in albacore's favor since I wrote the thing myself ;) but I still have docs for all options together with examples on how to use them.

I think a PR that implements the above would be an OK replacement for albacore, and given the consensus in the F# community, an improvement.

[tpetricek]

@haf Thanks for being this open about accepting PR that would use FAKE! I completely understand that (coming from another background) Albacore looks a lot more natural (I only learned FAKE because I was never a build guy :-)). If FAKE helps Suave get more help from the F# community, that would be great - Suave is a fantastic project already!

[ademar]

I've fixed two little things here cc @haf

[ademar]

As it is now it works on my Windows machine, for some reason on AppVeyor fsi.exe is not in the path.

I've pushed the generated docs here http://suave.io/reference/index.html

[haf]

Spending a couple of hours on this today, I had planned... =) Now it's rebased on master.

[dsyme]

@haf where is the content of the suave website these days? I see suaveIO/suave-website but it looks auto-generated?

[ademar]

@dsyme Yes, the contents of suaveIO/suave-website (out of which the Herokup app runs) are auto-generated using the scripts in this PR. A process I've failed to document properly.

It also uses a patched version of Fsharp.Formatting (ref fsprojects/FSharp.Formatting#331)

[dsyme]

Ah ok. So we can't easily submit PRs to the docs?

The thing I'm trying to fix is a missing ";;" in this example: http://suave.io/paket.html. There needs to be a ";;" at the end of step 1, like there is at the end of Step 2.

[ademar]

No, not easily. Give me a couple of days I'll clean it up and formalize the procedure.

[haf]

@ademar So this is what you used when gh-pages was html-only? It would seem we're back on markdown on the gh-pages branch, so that takes care of the 'contrib' use case. I'm considering moving all docs into the master branch, so they can be versioned alongside the rest of the code and using this PR as the code that builds it out to the gh-pages branch. What do you think?

[haf]

Closing in favor of FsLibTool, the F# formatting project is broken enough that after all of this work I've failed to properly make it work using the command line tool.