Initial docs generation using Fornax

Author: Krzysztof-Cieslak

fcs/.config/dotnet-tools.json

@@ -13,6 +13,12 @@
       "commands": [
         "paket"
       ]
+    },
+    "fornax": {
+      "version": "0.13.1",
+      "commands": [
+        "fornax"
+      ]
     }
   }
 }

fcs/.gitignore

@@ -11,3 +11,4 @@ FSharp.Compiler.Service.netstandard/pplex.fs
 FSharp.Compiler.Service.netstandard/pppars.fs
 FSharp.Compiler.Service.netstandard/pppars.fsi
 .idea/
+_public

fcs/docsrc/_lib/Fornax.Core.dll

@@ -0,0 +1,20 @@
+#r "_lib/Fornax.Core.dll"
+
+open Config
+
+let customRename (page: string) =
+    System.IO.Path.ChangeExtension(page.Replace ("content/", ""), ".html")
+
+let isScriptToParse (ap, rp : string) =
+    let folder = System.IO.Path.GetDirectoryName rp
+    folder.Contains "content" && rp.EndsWith ".fsx"
+
+let config = {
+    Generators = [
+        {Script = "page.fsx"; Trigger = OnFileExt ".md"; OutputFile = Custom customRename }
+        {Script = "page.fsx"; Trigger = OnFilePredicate isScriptToParse; OutputFile = Custom customRename }
+        {Script = "apiref.fsx"; Trigger = Once; OutputFile = MultipleFiles (sprintf "reference/%s.html") }
+
+        {Script = "lunr.fsx"; Trigger = Once; OutputFile = NewFileName "index.json" }
+    ]
+}

fcs/docsrc/config.fsx

@@ -1,3 +1,11 @@
+(**
+---
+category: how-to
+title: Notes on the FSharpChecker caches
+menu_order: 2
+
+---
+*)
 (*** hide ***)
 #I "../../../artifacts/bin/fcs/Release/netcoreapp3.0"
 (**
@@ -8,24 +16,24 @@ This is a design note on the FSharpChecker component and its caches.  See also t
 
 Each FSharpChecker object maintains a set of caches.  These are
 
-* ``scriptClosureCache`` - an MRU cache of default size ``projectCacheSize`` that caches the 
+* ``scriptClosureCache`` - an MRU cache of default size ``projectCacheSize`` that caches the
   computation of GetProjectOptionsFromScript. This computation can be lengthy as it can involve processing the transitive closure
   of all ``#load`` directives, which in turn can mean parsing an unbounded number of script files
 
-* ``incrementalBuildersCache`` - an MRU cache of projects where a handle is being kept to their incremental checking state, 
-  of default size ``projectCacheSize`` (= 3 unless explicitly set as a parameter).  
-  The "current background project" (see the [FSharpChecker operations queue](queue.html)) 
+* ``incrementalBuildersCache`` - an MRU cache of projects where a handle is being kept to their incremental checking state,
+  of default size ``projectCacheSize`` (= 3 unless explicitly set as a parameter).
+  The "current background project" (see the [FSharpChecker operations queue](queue.html))
   will be one of these projects.  When analyzing large collections of projects, this cache usually occupies by far the most memory.
   Increasing the size of this cache can dramatically decrease incremental computation of project-wide checking, or of checking
   individual files within a project, but can very greatly increase memory usage.
 
 * ``braceMatchCache`` - an MRU cache of size ``braceMatchCacheSize`` (default = 5) keeping the results of calls to MatchBraces, keyed by filename, source and project options.
 
-* ``parseFileCache`` - an MRU cache of size ``parseFileCacheSize`` (default = 2) keeping the results of ParseFile, 
+* ``parseFileCache`` - an MRU cache of size ``parseFileCacheSize`` (default = 2) keeping the results of ParseFile,
   keyed by filename, source and project options.
 
-* ``checkFileInProjectCache`` - an MRU cache of size ``incrementalTypeCheckCacheSize`` (default = 5) keeping the results of 
-  ParseAndCheckFileInProject, CheckFileInProject and/or CheckFileInProjectIfReady. This is keyed by filename, file source 
+* ``checkFileInProjectCache`` - an MRU cache of size ``incrementalTypeCheckCacheSize`` (default = 5) keeping the results of
+  ParseAndCheckFileInProject, CheckFileInProject and/or CheckFileInProjectIfReady. This is keyed by filename, file source
   and project options.  The results held in this cache are only returned if they would reflect an accurate parse and check of the
   file.
 
@@ -35,8 +43,8 @@ Each FSharpChecker object maintains a set of caches.  These are
   are all weak references, you can generally ignore this cache, since its entries will be automatically collected.
   Strong references to binary readers will be kept by other FCS data structures, e.g. any project checkers, symbols or project checking results.
 
-  In more detail, the bytes for referenced .NET binaries are read into memory all at once, eagerly. Files are not left 
-  open or memory-mapped when using FSharpChecker (as opposed to FsiEvaluationSession, which loads assemblies using reflection). 
+  In more detail, the bytes for referenced .NET binaries are read into memory all at once, eagerly. Files are not left
+  open or memory-mapped when using FSharpChecker (as opposed to FsiEvaluationSession, which loads assemblies using reflection).
   The purpose of this cache is mainly to ensure that while setting up compilation, the reads of mscorlib, FSharp.Core and so on
   amortize cracking the DLLs.
 
@@ -46,8 +54,8 @@ Each FSharpChecker object maintains a set of caches.  These are
 
 Profiling the memory used by the various caches can be done by looking for the corresponding static roots in memory profiling traces.
 
-The sizes of some of these caches can be adjusted by giving parameters to FSharpChecker.  Unless otherwise noted, 
-the cache sizes above indicate the "strong" size of the cache, where memory is held regardless of the memory 
+The sizes of some of these caches can be adjusted by giving parameters to FSharpChecker.  Unless otherwise noted,
+the cache sizes above indicate the "strong" size of the cache, where memory is held regardless of the memory
 pressure on the system. Some of the caches can also hold "weak" references which can be collected at will by the GC.
 
 > Note: Because of these caches, you should generally use one global, shared FSharpChecker for everything in an IDE application.
@@ -58,13 +66,13 @@ Low-Memory Condition
 
 Version 1.4.0.8 added a "maximum memory" limit specified by the `MaxMemory` property on FSharpChecker (in MB). If an FCS project operation
 is performed (see `CheckMaxMemoryReached` in `service.fs`) and `System.GC.GetTotalMemory(false)` reports a figure greater than this, then
-the strong sizes of all FCS caches are reduced to either 0 or 1.  This happens for the remainder of the lifetime of the FSharpChecker object. 
-In practice this will still make tools like the Visual Studio F# Power Tools usable, but some operations like renaming across multiple 
+the strong sizes of all FCS caches are reduced to either 0 or 1.  This happens for the remainder of the lifetime of the FSharpChecker object.
+In practice this will still make tools like the Visual Studio F# Power Tools usable, but some operations like renaming across multiple
 projects may take substantially longer.
 
-By default the maximum memory trigger is disabled, see `maxMBDefault` in `service.fs`. 
+By default the maximum memory trigger is disabled, see `maxMBDefault` in `service.fs`.
 
-Reducing the FCS strong cache sizes does not guarantee there will be enough memory to continue operations - even holding one project 
+Reducing the FCS strong cache sizes does not guarantee there will be enough memory to continue operations - even holding one project
 strongly may exceed a process memory budget. It just means FCS may hold less memory strongly.
 
 If you do not want the maximum memory limit to apply then set MaxMemory to System.Int32.MaxValue.
@@ -73,9 +81,9 @@ Summary
 -------
 
 In this design note, you learned that the FSharpChecker component keeps a set of caches in order to support common
-incremental analysis scenarios reasonably efficiently. They correspond roughly to the original caches and sizes 
+incremental analysis scenarios reasonably efficiently. They correspond roughly to the original caches and sizes
 used by the Visual F# Tools, from which the FSharpChecker component derives.
 
-In long running, highly interactive, multi-project scenarios you should carefully 
+In long running, highly interactive, multi-project scenarios you should carefully
 consider the cache sizes you are using and the tradeoffs involved between incremental multi-project checking and memory usage.
 *)

fcs/docsrc/content/caches.fsx

@@ -1,3 +1,11 @@
+(**
+---
+category: tutorial
+title: Hosted Compiler
+menu_order: 8
+
+---
+*)
 (*** hide ***)
 #I "../../../artifacts/bin/fcs/Release/netcoreapp3.0"
 (**
@@ -10,8 +18,8 @@ This tutorial demonstrates how to host the F# compiler.
 *)
 
 (**
-> **NOTE:** There are several options for hosting the F# compiler. The easiest one is to use the 
-`fsc.exe` process and pass arguments. 
+> **NOTE:** There are several options for hosting the F# compiler. The easiest one is to use the
+`fsc.exe` process and pass arguments.
 *)
 
 (**
@@ -31,7 +39,7 @@ First, we need to reference the libraries that contain F# interactive service:
 open System.IO
 open FSharp.Compiler.SourceCodeServices
 
-// Create an interactive checker instance 
+// Create an interactive checker instance
 let checker = FSharpChecker.Create()
 
 (**
@@ -45,7 +53,7 @@ let fn3 = Path.ChangeExtension(fn, ".dll")
 File.WriteAllText(fn2, """
 module M
 
-type C() = 
+type C() =
    member x.P = 1
 
 let x = 3 + 4
@@ -55,11 +63,11 @@ let x = 3 + 4
 Now invoke the compiler:
 *)
 
-let errors1, exitCode1 = 
-    checker.Compile([| "fsc.exe"; "-o"; fn3; "-a"; fn2 |]) 
+let errors1, exitCode1 =
+    checker.Compile([| "fsc.exe"; "-o"; fn3; "-a"; fn2 |])
     |> Async.RunSynchronously
 
-(** 
+(**
 
 If errors occur you can see this in the 'exitCode' and the returned array of errors:
 
@@ -70,7 +78,7 @@ module M
 let x = 1.0 + "" // a type error
 """)
 
-let errors1b, exitCode1b = 
+let errors1b, exitCode1b =
     checker.Compile([| "fsc.exe"; "-o"; fn3; "-a"; fn2 |])
     |> Async.RunSynchronously
 
@@ -85,16 +93,16 @@ is not really an option.
 
 You still have to pass the "-o" option to name the output file, but the output file is not actually written to disk.
 
-The 'None' option indicates that the initialization code for the assembly is not executed. 
+The 'None' option indicates that the initialization code for the assembly is not executed.
 *)
-let errors2, exitCode2, dynAssembly2 = 
+let errors2, exitCode2, dynAssembly2 =
     checker.CompileToDynamicAssembly([| "-o"; fn3; "-a"; fn2 |], execute=None)
      |> Async.RunSynchronously
 
 (*
 Passing 'Some' for the 'execute' parameter executes  the initialization code for the assembly.
 *)
-let errors3, exitCode3, dynAssembly3 = 
+let errors3, exitCode3, dynAssembly3 =
     checker.CompileToDynamicAssembly([| "-o"; fn3; "-a"; fn2 |], Some(stdout,stderr))
      |> Async.RunSynchronously
 

fcs/docsrc/content/compiler.fsx

@@ -1,3 +1,11 @@
+(**
+---
+category: how-to
+title: Notes on FSharp.Core.dll
+menu_order: 3
+
+---
+*)
 (*** hide ***)
 #I "../../../artifacts/bin/fcs/Release/netcoreapp3.0"
 (**

fcs/docsrc/content/corelib.fsx

@@ -1,3 +1,9 @@
+---
+title: Developer Notes
+category: explanation
+menu_order: 2
+---
+
 Developer notes
 ===============
 
@@ -6,9 +12,9 @@ and F# interactive as services.
 
 ## Components
 
-There is one main component, `FSharp.Compiler.Service.dll`. 
-The main aim is to have a stable and documented fork of the main compiler that allows various 
-tools to share this common code.  
+There is one main component, `FSharp.Compiler.Service.dll`.
+The main aim is to have a stable and documented fork of the main compiler that allows various
+tools to share this common code.
 This component allows embedding F# Interactive as a service and contains a number of
 modifications to the source code of `fsi.exe` that adds `EvalExpression` and `EvalInteraction` functions.
 
@@ -19,7 +25,7 @@ This repo should be _identical_ to 'fsharp' except:
     - Only build `FSharp.Compiler.Service.dll`
     - No bootstrap or proto compiler is used - an installed F# compiler is assumed
 
-  - Build script using FAKE that builds everything, produces NuGet package and 
+  - Build script using FAKE that builds everything, produces NuGet package and
     generates documentation, files for publishing NuGet packages etc.
     (following [F# project scaffold](https://github.com/fsprojects/FSharp.ProjectScaffold))