this is me trying to follow your example @fbmnds

.gitignore

@@ -14,3 +14,5 @@ suave.sln.DotSettings.user
 gh-pages/
 AssemblyVersionInfo.fs
 miTLS/
+buildsupport/FSharp.Formatting.CommandTool/
+buildsupport/FSharp.Core.Open.FS31/

Rakefile

@@ -69,28 +69,23 @@ task :create_nuget_quick => ['build/pkg', :versioning] do
     m.language      = 'en-GB'
     m.copyright     = 'Ademar Gonzalez'
     m.release_notes = "Full version: #{ENV['BUILD_VERSION']}."
-    m.license_url       = "https://github.com/ademar/suave/blob/master/COPYING"
-    m.project_url    = "http://suave.io"
+    m.license_url   = "https://github.com/ademar/suave/blob/master/COPYING"
+    m.project_url   = "http://suave.io"
   end
   p.add_file  "Suave/bin/Release/suave.dll", "lib"
   p.add_file  "Suave/bin/Release/suave.xml", "lib"
-  nuspec_path = 'suave.nuspec'
-  File.write(nuspec_path,p.to_xml)
-  cmd = Albacore::NugetsPack::Cmd.new "buildsupport/NuGet.exe", out: "build/pkg"
-  pkg, spkg = cmd.execute nuspec_path
+
+  File.write('suave.nuspec', p.to_xml)
+  cmd = Albacore::NugetsPack::Cmd.new 'buildsupport/NuGet.exe', out: 'build/pkg'
+  pkg, _ = cmd.execute 'suave.nuspec'
+
   Albacore.publish :artifact, OpenStruct.new(
-    :nuspec   => nuspec_path,
+    :nuspec   => 'suave.nuspec',
     :nupkg    => pkg,
     :location => pkg
   )
 end
 
-desc 'create suave nuget'
-task :create_nuget => ['build/pkg', :versioning, :build, :create_nuget_quick]
-
-desc 'build, gen versions, test and create nuget'
-task :default => [:build, :'tests:unit']
-
 task :increase_version_number do
   # inc patch version in .semver
   s = SemVer.find
@@ -117,9 +112,12 @@ namespace :docs do
     FileUtils.rm_rf 'gh-pages' if Dir.exists? 'gh-pages'
   end
 
-  desc 'build documentation'
-  task :build => :clean do
+  task :clone_gh_pages do
     system 'git clone https://github.com/SuaveIO/suave.git -b gh-pages gh-pages' unless Dir.exists? 'gh-pages'
+  end
+
+  desc 'build documentation'
+  task :text => [:clean, :clone_gh_pages] do
     Dir.chdir 'gh-pages' do
       Bundler.with_clean_env do
         system 'bundle'
@@ -128,9 +126,57 @@ namespace :docs do
     end
   end
 
+  def nuget_install package
+    system 'buildsupport/NuGet.exe',
+%W|install #{package}
+      -OutputDirectory buildsupport/
+      -ExcludeVersion|,
+        clr_command: true
+  end
+
+  task :fsformatting do
+    nuget_install 'FSharp.Core.Open.FS31'
+    nuget_install 'FSharp.Formatting.CommandTool'
+    FileUtils.cp_r 'buildsupport/FSharp.Core.Open.FS31/lib/net40/.', 'buildsupport/FSharp.Formatting.CommandTool/tools/' unless
+      ENV['DO_NOT_OVERWRITE']
+  end
+
+  task :api_quick do
+    # use templates e.g of Fake project at 'https://github.com/fsharp/FAKE/tree/master/help/templates'
+    md = %w|page-description F#\ Suave
+            page-author      Ademar\ Gonzalez,\ Henrik\ Feldt
+            project-author   Ademar\ Gonzalez,\ Henrik\ Feldt
+            github-link      https://github.com/SuaveIO/suave
+            project-github   https://github.com/SuaveIO/suave
+            project-nuget    https://www.nuget.org/packages/Suave
+            root             http://suave.io
+            project-name     Suave|
+
+    # transform parameter into one string, separated by blanks, embedded into double quotes
+    # transform cmd into one string, separated by blanks
+    system 'buildsupport/FSharp.Formatting.CommandTool/tools/fsformatting.exe',
+%W|metadataFormat
+  --generate
+  --dllFiles #{File.join(FileUtils.pwd, 'Suave/bin/Release/suave.dll')}
+  --outDir gh-pages/api
+  --layoutRoots gh-pages/_fs_formatting/reference
+  --sourceRepo https://github.com/SuaveIO/suave/tree/master/Suave
+  --sourceFolder Suave
+  --parameters|.concat(md).flatten, clr_command: true
+  end
+
+  desc 'build API docs'
+  task :api => [:build, :fsformatting, :clone_gh_pages, :api_quick]
+
   desc 'build and push docs'
-  task :push => :'docs:build' do
+  task :push => :'docs:text' do
     system "sshpass -p #{ENV['SUAVE_SERVER_PASS']} scp -P #{ENV['SUAVE_SERVER_PORT']} -r _site/* [email protected]:/home/suave/site",
       work_dir: 'gh-pages'
   end
 end
+
+desc 'create suave nuget'
+task :create_nuget => ['build/pkg', :versioning, :build, :create_nuget_quick]
+
+desc 'build, gen versions, test and create nuget'
+task :default => [:build, :'tests:unit', :'docs:api']