Docs: start migrating links from numerics homepage to docs; doc gener…

…ation tweaks mathnet#272
cdrnet · Jan 11, 2015 · f110319 · f110319
1 parent 1561d50
commit f110319
Show file tree

Hide file tree

Showing 6 changed files with 72 additions and 42 deletions.
diff --git a/.gitignore b/.gitignore
@@ -24,6 +24,7 @@ coverage.*
 
 # Caches
 _ReSharper*
+_TeamCity*
 *.[Rr]e[Ss]harper
 *.ide/
 *.[Cc]ache
@@ -39,6 +40,7 @@ Backup*/
 UpgradeLog*.XML
 UpgradeLog*.htm
 *.bak
+*.orig
 
 # OS
 $RECYCLE.BIN/
@@ -60,3 +62,10 @@ packages/*
 # FAKE & Paket
 packages/FAKE
 tools/paket/paket.exe
+
+# Generated Doc Files
+docs/content/License.md
+docs/content/Contributing.md
+docs/content/Contributors.md
+docs/content/ReleaseNotes.md
+docs/content/ReleaseNotes-*.md
diff --git a/LICENSE.md b/LICENSE.md
@@ -1,7 +1,7 @@
 Math.NET Numerics License (MIT/X11)
 ===================================
 
-Copyright (c) 2002-2014 Math.NET
+Copyright (c) 2002-2015 Math.NET
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

diff --git a/RELEASENOTES-MKL.md b/RELEASENOTES-MKL.md
@@ -1,9 +1,9 @@
 ### 1.7.0 - 2014-12-31
 * r7 with Intel MKL 11.2 Update 1
-* memory functions
+* memory functions *~Marcus Cuda*
 
 ### 1.6.0 - 2014-06-21
-* r6 with Intel MKL 11.1 Update 3  
+* r6 with Intel MKL 11.1 Update 3
 * capability to control max number of threads
 
 ### 1.5.0 - 2014-06-15

diff --git a/build.fsx b/build.fsx
@@ -24,6 +24,7 @@ open Fake.AssemblyInfoFile
 open Fake.ReleaseNotesHelper
 open Fake.StringHelper
 open System
+open System.IO
 
 Environment.CurrentDirectory <- __SOURCE_DIRECTORY__
 let header = ReadFile(__SOURCE_DIRECTORY__ @@ "build.fsx") |> Seq.take 10 |> Seq.map (fun s -> s.Substring(2)) |> toLines
@@ -563,19 +564,61 @@ Target "DataNuGet" (fun _ ->
 
 Target "CleanDocs" (fun _ -> CleanDirs ["out/docs"])
 
-Target "Docs" (fun _ ->
-    executeFSIWithArgs "docs/tools" "build-docs.fsx" ["--define:RELEASE"] [] |> ignore
-)
+let extraDocs =
+    [ "LICENSE.md", "License.md"
+      "CONTRIBUTING.md", "Contributing.md"
+      "CONTRIBUTORS.md", "Contributors.md" ]
+
+let releaseNotesDocs =
+    [ "RELEASENOTES.md", "ReleaseNotes.md", "Release Notes"
+      "RELEASENOTES-Data.md", "ReleaseNotes-Data.md", "Data Extensions Release Notes"
+      "RELEASENOTES-MKL.md", "ReleaseNotes-MKL.md", "MKL Native Provider Release Notes" ]
+
+let provideDocExtraFiles() =
+    for (fileName, docName) in extraDocs do CopyFile ("docs/content" @@ docName) fileName
+    for (fileName, docName, title) in releaseNotesDocs do
+        String.concat Environment.NewLine
+          [ "# " + title
+            "[Math.NET Numerics](ReleaseNotes.html) | [Data Extensions](ReleaseNotes-Data.html) | [MKL Native Provider](ReleaseNotes-MKL.html)"
+            ""
+            ReadFileAsString fileName ]
+        |> ReplaceFile ("docs/content" @@ docName)
+
+let generateDocs fail local =
+    let args = if local then [] else ["--define:RELEASE"]
+    if executeFSIWithArgs "docs/tools" "build-docs.fsx" args [] then
+         traceImportant "Docs generated"
+    else
+        if fail then
+            failwith "Generating documentation failed"
+        else
+            traceImportant "generating documentation failed"
 
+Target "Docs" (fun _ ->
+    provideDocExtraFiles ()
+    generateDocs true false)
 Target "DocsDev" (fun _ ->
-    executeFSIWithArgs "docs/tools" "build-docs.fsx" [] [] |> ignore
-)
+    provideDocExtraFiles ()
+    generateDocs true true)
+Target "DocsWatch" (fun _ ->
+    provideDocExtraFiles ()
+    use watcher = new FileSystemWatcher(DirectoryInfo("docs/content").FullName, "*.*")
+    watcher.EnableRaisingEvents <- true
+    watcher.Changed.Add(fun e -> generateDocs false true)
+    watcher.Created.Add(fun e -> generateDocs false true)
+    watcher.Renamed.Add(fun e -> generateDocs false true)
+    watcher.Deleted.Add(fun e -> generateDocs false true)
+    traceImportant "Waiting for docs edits. Press any key to stop."
+    System.Console.ReadKey() |> ignore
+    watcher.EnableRaisingEvents <- false
+    watcher.Dispose())
 
 "CleanDocs" ==> "Docs"
 
 "Start"
   =?> ("CleanDocs", not (hasBuildParam "incremental"))
   ==> "DocsDev"
+  ==> "DocsWatch"
 
 
 // API REFERENCE

diff --git a/docs/tools/build-docs.fsx b/docs/tools/build-docs.fsx
@@ -20,12 +20,11 @@ let info =
 // For typical project, no changes are needed below
 // --------------------------------------------------------------------------------------
 
+#I "../../packages/FSharp.Formatting/lib/net40"
+#I "../../packages/RazorEngine/lib/net40"
 #I "../../packages/FSharp.Compiler.Service/lib/net40"
-#I "../../packages/RazorEngine/lib/net40/"
 #r "../../packages/Microsoft.AspNet.Razor/lib/net40/System.Web.Razor.dll"
-#I "../../packages/FSharp.Formatting/lib/net40"
 #r "../../packages/FAKE/tools/FakeLib.dll"
-#r "FSharp.Compiler.Service.dll"
 #r "RazorEngine.dll"
 #r "FSharp.Literate.dll"
 #r "FSharp.CodeFormat.dll"
@@ -62,42 +61,20 @@ let layoutRoots =
       formatting @@ "templates"
       formatting @@ "templates/reference" ]
 
-let extraDocs =
-    [ "LICENSE.md", "License.md"
-      "CONTRIBUTING.md", "Contributing.md"
-      "CONTRIBUTORS.md", "Contributors.md" ]
-
-let releaseNotesDocs =
-    [ "RELEASENOTES.md", "ReleaseNotes.md", "Release Notes"
-      "RELEASENOTES-Data.md", "ReleaseNotes-Data.md", "Data Extensions Release Notes"
-      "RELEASENOTES-MKL.md", "ReleaseNotes-MKL.md", "MKL Native Provider Release Notes" ]
-
 // Copy static files and CSS + JS from F# Formatting
 let copySupportFiles() =
     CopyRecursive files output true |> Log "Copying file: "
     ensureDirectory (output @@ "content")
     CopyRecursive (formatting @@ "styles") (output @@ "content") true |> Log "Copying styles and scripts: "
 
-let copyExtraDocs() =
-    for (fileName, docName) in extraDocs do CopyFile (content @@ docName) (top @@ fileName)
-
-let prepareReleaseNotes() =
-    for (fileName, docName, title) in releaseNotesDocs do
-        String.concat Environment.NewLine
-          [ "# " + title
-            "[Math.NET Numerics](ReleaseNotes.html) | [Data Extensions](ReleaseNotes-Data.html) | [MKL Native Provider](ReleaseNotes-MKL.html)"
-            ""
-            ReadFileAsString (top @@ fileName) ]
-        |> ReplaceFile (content @@ docName)
-
 // Build API reference from XML comments
 let buildReference() =
     CleanDir(output @@ "reference")
     for lib in referenceBinaries do
         MetadataFormat.Generate
             (bin @@ lib, output @@ "reference", layoutRoots, parameters = ("root", root) :: info,
              sourceRepo = "https://github.com/mathnet/mathnet-numerics/tree/master/src", sourceFolder = @"..\..\src",
-             publicOnly = true)
+             publicOnly = true, libDirs = [bin])
 
 // Build documentation from `fsx` and `md` files in `docs/content`
 let buildDocumentation() =
@@ -108,14 +85,8 @@ let buildDocumentation() =
             (dir, docTemplate, output @@ sub, replacements = ("root", root) :: info, layoutRoots = layoutRoots,
              references = false, lineNumbers = true, generateAnchors = true)
 
-let cleanup() =
-    for (_, docName) in extraDocs do DeleteFile (content @@ docName)
-    for (_, docName, _) in releaseNotesDocs do DeleteFile (content @@ docName)
 
 // Generate
 copySupportFiles()
-copyExtraDocs()
-prepareReleaseNotes()
 buildDocumentation()
 buildDocumentation()
-cleanup()
diff --git a/docs/tools/templates/template.cshtml b/docs/tools/templates/template.cshtml
@@ -33,7 +33,7 @@
                     <li><a href="https://github.com/mathnet/mathnet-numerics">GitHub</a></li>
                     <li><a href="https://mathnetnumerics.codeplex.com/">CodePlex</a></li>
                 </ul>
-                <h3 class="muted">Math.NET Numerics Documentation</h3>
+                <h3 class="muted">Math.NET Numerics</h3>
             </div>
             <hr />
             <div class="row">
@@ -46,12 +46,19 @@
                         <li class="nav-header">Math.NET Numerics</li>
                         <li><a href="http://numerics.mathdotnet.com">Project Website</a></li>
                         <li><a href="@Root/ReleaseNotes.html">Release Notes</a></li>
+                        <li><a href="@Root/License.html">MIT/X11 License</a></li>
                         <li><a href="@Root/Contributors.html">Contributors</a></li>
                         <li><a href="@Root/Contributing.html">Contributing</a></li>
-                        <li><a href="@Root/License.html">MIT/X11 License</a></li>
                         <li><a href="http://numerics.mathdotnet.com/api/">Class Reference</a></li>
+                        <li><a href="https://github.com/mathnet/mathnet-numerics/issues">Issues & Bugs</a></li>
+                        <li><a href="http://feedback.mathdotnet.com/forums/2060-math-net-numerics">Your Ideas</a></li>
                         <li><a href="@Root/Users.html">Who is using Math.NET?</a></li>
 
+                        <li class="nav-header">Getting Help</li>
+                        <li><a href="http://stackoverflow.com/questions/tagged/mathdotnet">Stack Overflow</a></li>
+                        <li><a href="http://mathnetnumerics.codeplex.com/discussions">Discuss</a></li>
+                        <li><a href="https://gitter.im/mathnet/mathnet-numerics">Chat</a></li>
+
                         <li class="nav-header">Getting Started</li>
                         <li><a href="@Root/">Getting started</a></li>
                         <li>Constants</li>