From 5763d568b45a93f639b058a2f5e520f860d2bd49 Mon Sep 17 00:00:00 2001 From: Anairkoen Schno Date: Sun, 21 Jul 2019 04:44:16 -0500 Subject: [PATCH] Started on work to generate documentation for config file --- IPA.Loader/Config/SelfConfig.cs | 13 +++++-- docs/.gitignore | 3 +- docs/build.ps1 | 66 ++++++++++++++++++++++++++++++++ docs/docfx.json | 5 +++ docs/other_api/config/.gitignore | 1 + docs/other_api/config/index.md | 1 + docs/other_api/config/schema.md | 7 ++++ docs/other_api/index.md | 5 +++ docs/other_api/toc.yml | 9 +++++ docs/toc.yml | 5 ++- 10 files changed, 110 insertions(+), 5 deletions(-) create mode 100644 docs/build.ps1 create mode 100644 docs/other_api/config/.gitignore create mode 100644 docs/other_api/config/index.md create mode 100644 docs/other_api/config/schema.md create mode 100644 docs/other_api/index.md create mode 100644 docs/other_api/toc.yml diff --git a/IPA.Loader/Config/SelfConfig.cs b/IPA.Loader/Config/SelfConfig.cs index 44e53ba0..ce588cf0 100644 --- a/IPA.Loader/Config/SelfConfig.cs +++ b/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; } } \ No newline at end of file diff --git a/docs/.gitignore b/docs/.gitignore index 271d66a8..d5113c3c 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -3,4 +3,5 @@ /**/TEMP/ /**/packages/ /**/bin/ -/obj \ No newline at end of file +/obj +/nuget \ No newline at end of file diff --git a/docs/build.ps1 b/docs/build.ps1 new file mode 100644 index 00000000..e2a529ab --- /dev/null +++ b/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." +} \ No newline at end of file diff --git a/docs/docfx.json b/docs/docfx.json index 06b27f3c..c0840c6d 100644 --- a/docs/docfx.json +++ b/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" ] diff --git a/docs/other_api/config/.gitignore b/docs/other_api/config/.gitignore new file mode 100644 index 00000000..5ac4f0f4 --- /dev/null +++ b/docs/other_api/config/.gitignore @@ -0,0 +1 @@ +_schema.json \ No newline at end of file diff --git a/docs/other_api/config/index.md b/docs/other_api/config/index.md new file mode 100644 index 00000000..884a64ed --- /dev/null +++ b/docs/other_api/config/index.md @@ -0,0 +1 @@ +# Title 2 \ No newline at end of file diff --git a/docs/other_api/config/schema.md b/docs/other_api/config/schema.md new file mode 100644 index 00000000..9842f4f7 --- /dev/null +++ b/docs/other_api/config/schema.md @@ -0,0 +1,7 @@ +--- +uid: other.config.schema +--- + +# Configuration File Schema + +[!code[Schema File](_schema.json)] diff --git a/docs/other_api/index.md b/docs/other_api/index.md new file mode 100644 index 00000000..f3d57b9c --- /dev/null +++ b/docs/other_api/index.md @@ -0,0 +1,5 @@ +--- +uid: other.index +--- + +# Title1 \ No newline at end of file diff --git a/docs/other_api/toc.yml b/docs/other_api/toc.yml new file mode 100644 index 00000000..0dabc6ac --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/toc.yml b/docs/toc.yml index 30e21122..ace93a2c 100644 --- a/docs/toc.yml +++ b/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