Started on work to generate documentation for config file

IPA.Loader/Config/SelfConfig.cs

@@ -1,14 +1,16 @@
-using IPA.JsonConverters;
+// BEGIN: section ignore
 using IPA.Logging;
 using IPA.Utilities;
+// END: section ignore
 using Newtonsoft.Json;
-using SemVer;
-using System;
 
 namespace IPA.Config
 {
     internal class SelfConfig
     {
+        // This is to allow the doc generation to parse this file and use Newtonsoft to generate a JSON schema
+        // BEGIN: section ignore
+
         private static IConfigProvider _loaderConfig;
 
         public static IConfigProvider LoaderConfig
@@ -39,6 +41,8 @@ namespace IPA.Config
         internal const string IPAName = "Beat Saber IPA";
         internal const string IPAVersion = "3.12.24"; 
 		
+        // END: section ignore
+
         public bool Regenerate = true;
 
         public class UpdateObject
@@ -47,6 +51,7 @@ namespace IPA.Config
             public bool AutoCheckUpdates = true;
         }
 
+        [JsonProperty(Required = Required.Always)]
         public UpdateObject Updates = new UpdateObject();
 
         public class DebugObject
@@ -58,8 +63,10 @@ namespace IPA.Config
             public int HideLogThreshold = 512;
         }
 
+        [JsonProperty(Required = Required.Always)]
         public DebugObject Debug = new DebugObject();
 
+        [JsonProperty(Required = Required.Default)]
         public string LastGameVersion = null;
     }
 }

docs/.gitignore

@@ -3,4 +3,5 @@
 /**/TEMP/
 /**/packages/
 /**/bin/
-/obj
+/obj
+/nuget

docs/build.ps1

@@ -0,0 +1,66 @@
+& docfx metadata
+
+# read SelfConfig, remove wierd bits, load it, load Newtonsoft, and turn it into a schema
+$newtonsoftLoc = "nuget/Newtonsoft.Json.12.0.2/lib/netstandard2.0/Newtonsoft.Json.dll"
+$newtonsoftSchemaLoc = "nuget/Newtonsoft.Json.Schema.3.0.11/lib/netstandard2.0/Newtonsoft.Json.Schema.dll"
+$selfConfigLoc = "../IPA.Loader/Config/SelfConfig.cs"
+
+if (!(Test-Path "nuget" -PathType Container)) {
+    nuget install Newtonsoft.Json -Version 12.0.2 -source https://api.nuget.org/v3/index.json -o nuget
+    nuget install Newtonsoft.Json.Schema -Version 3.0.11 -source https://api.nuget.org/v3/index.json -o nuget
+}
+
+if ((Test-Path $newtonsoftLoc -PathType Leaf) -and (Test-Path $selfConfigLoc -PathType Leaf)) {
+    # The files we need exist, lets do this!
+
+    # First load Newtonsoft
+    Add-Type -Path $newtonsoftLoc
+    Add-Type -Path $newtonsoftSchemaLoc
+
+    # Read and parse special directives from SelfConfig
+    function Process-Lines {
+        begin {
+            $inIgnoreSection = $false
+        }
+        process {
+            if ( $_ -match "^\s*//\s+([A-Z]+):\s+section\s+(.+)\s*$" ) {
+                $Begin = ($Matches[1] -eq "BEGIN")
+                $End = ($Matches[1] -eq "END")
+                switch ($Matches[2]) {
+                    "ignore" { 
+                        if ($Begin) { $inIgnoreSection = $true }
+                        if ($End) { $inIgnoreSection = $false }
+                    }
+                }
+            }
+
+            if ($inIgnoreSection) { "" }
+            else { $_ }
+        }
+    }
+
+    function Merge-Lines {
+        begin { $str = "" }
+        process { $str = $str + "`n" + $_ }
+        end { $str }
+    }
+
+    function Filter-Def {
+        process { $_ -replace "internal", "public" }
+    }
+
+    Add-Type -TypeDefinition (Get-Content $selfConfigLoc | Process-Lines | Merge-Lines | Filter-Def) -ReferencedAssemblies $newtonsoftLoc,"netstandard"
+
+    # type will be [IPA.Config.SelfConfig]
+
+    # Generate schema
+    $schemagen = New-Object -TypeName Newtonsoft.Json.Schema.Generation.JSchemaGenerator
+    $schema = $schemagen.Generate([IPA.Config.SelfConfig])
+
+    $schema.ToString() | Out-File "other_api/config/_schema.json"
+}
+
+& docfx build --globalMetadataFiles link_branch.json @Args
+if ($lastexitcode -ne 0) {
+    throw [System.Exception] "docfx build failed with exit code $lastexitcode."
+}

docs/docfx.json

@@ -6,8 +6,10 @@
         "**.csproj"
       ],
       "exclude": [
+        "**/BSIPA-Meta.csproj",
         "**/IPA.csproj",
         "**/IPA.Tests.csproj",
+        "TMP Exporter/**.csproj",
         "BuildTools/**.csproj",
         "Doorstop/**.csproj"
       ]
@@ -27,6 +29,9 @@
         "files": [
           "articles/**.md",
           "articles/**/toc.yml",
+          "other_api/**.md",
+          "other_api/**/toc.yml",
+          "other_api/**.yml",
           "toc.yml",
           "*.md"
         ]

docs/other_api/config/.gitignore

@@ -0,0 +1 @@
+_schema.json

docs/other_api/config/index.md

@@ -0,0 +1 @@
+# Title 2

docs/other_api/config/schema.md

@@ -0,0 +1,7 @@
+---
+uid: other.config.schema
+---
+
+# Configuration File Schema
+
+[!code[Schema File](_schema.json)]

docs/other_api/index.md

@@ -0,0 +1,5 @@
+---
+uid: other.index
+---
+
+# Title1

docs/other_api/toc.yml

@@ -0,0 +1,9 @@
+- name: Other APIs
+  href: index.md
+- name: Configuration File
+  href: config/schema.md
+  items:
+  - name: Schema
+    href: config/schema.md
+  - name: Index
+    href: config/index.md

docs/toc.yml

@@ -1,6 +1,9 @@
 - name: Articles
   href: articles/
   homepage: articles/index.md
-- name: Api Documentation
+- name: C# API Documentation
   href: api/
   homepage: api/index.md
+- name: Other API Documentation
+  href: other_api/
+  homepage: other_api/index.md