docs

Spriggit.CLI.Lib/Commands/DeserializeCommand.cs

@@ -6,19 +6,19 @@ namespace Spriggit.CLI.Commands;
 [Verb("deserialize", aliases: new[] { "create-plugin", "convert-to-plugin" }, HelpText = "Converts a mod from its text based representation to a binary Bethesda plugin")]
 public class DeserializeCommand
 {
-    [Option('i', "InputPath", HelpText = "Path to the Bethesda plugin as its text representation", Required = true)]
+    [Option('i', "InputPath", HelpText = "Path to the Bethesda plugin folder as its Spriggit text representation", Required = true)]
     public string InputPath { get; set; } = string.Empty;
 
-    [Option('o', "OutputPath", HelpText = "File export mod as its Bethesda plugin representation", Required = true)]
+    [Option('o', "OutputPath", HelpText = "Path to export the mod as its Bethesda plugin representation", Required = true)]
     public FilePath OutputPath { get; set; } = string.Empty;
 
     [Option('p', "PackageName",
-        HelpText = "Spriggit serialization nuget package to use for conversion",
+        HelpText = "Spriggit serialization nuget package to use for conversion.  Leave blank to auto detect",
         Required = false)]
     public string PackageName { get; set; } = string.Empty;
 
     [Option('v', "PackageVersion",
-        HelpText = "Spriggit serialization nuget package version to use for conversion",
+        HelpText = "Spriggit serialization nuget package version to use for conversion.  Leave blank to auto detect",
         Required = false)]
     public string PackageVersion { get; set; } = string.Empty;
 

Spriggit.CLI.Lib/Commands/SerializeCommand.cs

@@ -13,7 +13,7 @@ public class SerializeCommand
     public FilePath InputPath { get; set; } = string.Empty;
 
     [Option('o', "OutputPath",
-        HelpText = "Folder to export mod as its text representation",
+        HelpText = "Dedicated folder to export mod as its text representation",
         Required = true)]
     public DirectoryPath OutputPath { get; set; } = string.Empty;
 
@@ -23,7 +23,7 @@ public class SerializeCommand
     public GameRelease? GameRelease { get; set; }
 
     [Option('p', "PackageName",
-        HelpText = "Spriggit serialization nuget package to use for conversion",
+        HelpText = "Spriggit serialization nuget package name to use for conversion",
         Required = false)]
     public string PackageName { get; set; } = string.Empty;
 

docs/cli.md

@@ -0,0 +1,70 @@
+# Command Line Interface
+Spriggit comes with a Command Line Interface that can be used to convert from Betheseda Plugins to Git Repositories, and back. 
+
+These commands have parameters that are optional only if a .spriggit file is found.
+
+[:octicons-arrow-right-24: .spriggit File](spriggit-file.md)
+
+## Serialize | Convert From Plugin
+`serialize`, or `convert-from-plugin`
+
+This converts from a Bethesda Plugin mod to Yaml, and puts it in your Git Repository.
+
+### Typical
+`.\Path\To\Spriggit.CLI.exe convert-from-plugin --InputPath "C:\Games\steamapps\common\Skyrim Special Edition\Data\SomeMod.esp" --OutputPath "C:\MyGitRepository\SomeMod.esp" --GameRelease SkyrimSE --PackageName Spriggit.Yaml`
+
+### Parameters
+
+| Short | Long | Required | Description |
+| ---- | ---- | ---- | ---- |
+| `-i` | `--InputPath` | Required | Path to the Bethesda plugin (esp/esm) |
+| `-o` | `--OutputPath` | Required | Dedicated folder to export mod as its text representation |
+| `-g` | `--GameRelease` | Semi | Game release that the plugin is related to.  Required if no `.spriggit` file is found. |
+| `-p` | `--PackageName` | Optional | Spriggit serialization nuget package name to use for conversion |
+| `-v` | `--PackageVersion` | Optional | Spriggit serialization nuget package version to use for conversion |
+| `-t` | `--Threads` | Optional | Maximum number of threads to use |
+| `-d` | `--Debug` | Optional | Set up for debug mode, including resetting nuget caches |
+
+## Deserialize | Convert To Plugin
+`deserialize`, `convert-to-plugin`, `create-plugin`
+
+This converts from a folder in your Git Repository to a Bethesda Plugin.
+
+### Typical
+`.\Path\To\Spriggit.CLI.exe convert-to-plugin --InputPath "C:\Users\Levia\Downloads\SpriggitOutput\SomeMod.esp" --OutputPath "C:\MyGitRepository\SomeMod.esp"`s
+
+### Parameters
+| Short | Long | Required | Description |
+| ---- | ---- | ---- | ---- |
+| `-i` | `--InputPath` | Required | Path to the Bethesda plugin folder as its Spriggit text representation |
+| `-o` | `--OutputPath` | Required | Path to export the mod as its Bethesda plugin representation |
+| `-p` | `--PackageName` | Optional | Spriggit serialization nuget package name to use for conversion.  Leave blank to auto detect |
+| `-v` | `--PackageVersion` | Optional | Spriggit serialization nuget package version to use for conversion.  Leave blank to auto detect |
+| `-t` | `--Threads` | Optional | Maximum number of threads to use |
+| `-d` | `--Debug` | Optional | Set up for debug mode, including resetting nuget caches |
+
+!!! tip "Omit Package Details"
+    Spriggit stores the package details it was created with, so in most circumstances, you want to let it automatically detect the package information.
+
+## FormID Collision Fixing
+`formid-collision`
+
+This command helps detangle colliding FormIDs that result after a Git Merge.
+
+[:octicons-arrow-right-24: FormID Collision](merge-conflicts.md#formid-collision)
+
+!!! bug "Two Collisions Maximum"
+    The logic that Spriggit contains to handle FormID conflicts can only handle two records with a single FormID.  As such, collisions need to be handled immediately after each Git merge.
+
+### Typical
+`.\Path\To\Spriggit.CLI.exe convert-from-plugin --SpriggitPath "C:\MyGitRepository\SomeMod.esp"`
+
+### Parameters
+| Short | Long | Required | Description |
+| ---- | ---- | ---- | ---- |
+| `-p` | `--SpriggitPath` | Required | Path to the Bethesda plugin folder as its Spriggit text representation |
+| `-d` | `--Debug` | Optional | Set up for debug mode, including resetting nuget caches |
+
+
+
+

docs/installation.md

@@ -1,17 +1,20 @@
 # Installation
+Spriggit comes as a UI and a Command Line Interface.   Both can be downloaded from the github releases page
+
+[:octicons-arrow-right-24: Download](https://github.com/Mutagen-Modding/Spriggit/releases)
+
 ## Spriggit UI
 This is a self-contained WPF application, which can only run on Windows.  You can add links between a mod file and where it should be translated to, and then sync back and forth with one click.
 
-![Spriggit UI](images/Spiggit-ui-1.png)
-![Spriggit UI](images/Spiggit-ui-2.png)
+![Spriggit UI](images/spriggit-ui-1.png)
+![Spriggit UI](images/spriggit-ui-2.png)
 
 ## Spriggit CLI
-Spriggit comes with a Command Line Interface that can be used to convert from Betheseda Plugins to Git Repositories, and back.   Note that the UI can also accept these CLI commands, and so this variant is meant for linux machines that cannot handle the UI.   It is not self contained, so it might complain about needing a specific .NET runtime downloaded.
-
-This would use Spriggit to convert from a SkyrimSE mod to Yaml, and put it in your Git Repository.
+Spriggit comes with a Command Line Interface that can be used to convert from Betheseda Plugins to Git Repositories, and back.   
 
-`.\Path\To\Spriggit.CLI.exe serialize --InputPath "C:\Games\steamapps\common\Skyrim Special Edition\Data\SomeMod.esp" --OutputPath "C:\MyGitRepository\SomeMod.esp" --GameRelease SkyrimSE --PackageName Spriggit.Yaml`
+!!! tip "UI Can Also Run as a CLI"
+    The UI executable can also be run as a command line interface.
 
-And this would convert it back and overwrite the original mod file.
+For more details on the various commands that can be run:
 
-`.\Path\To\Spriggit.CLI.exe deserialize --InputPath "C:\Users\Levia\Downloads\SpriggitOutput\SomeMod.esp" --OutputPath "C:\MyGitRepository\SomeMod.esp"`
+[:octicons-arrow-right-24: Command Line Interface](cli.md)

docs/merge-conflicts.md

@@ -0,0 +1,26 @@
+# Merge Conflicts
+
+One of the powerful concepts that Spriggit + Git opens up is the ability to work on several branches in parallel.   Inevitably, this work needs to be merged together at some point, which can result in merge conflicts.
+
+## Typical Content Conflicts
+
+Merge conflicts are normal, but do need to be dealt with when they arise.  Typically this will arise if two sides modified the same fields on a record, where it's unsure which change you wanted to keep in the final result.
+
+You can google more about general Git merge conflict handling
+
+[:octicons-arrow-right-24: Git Merge Conflicts](https://www.gitkraken.com/learn/git/tutorials/how-to-resolve-merge-conflict-in-git)
+
+## FormID Collision
+A concept that is unique to Bethesda mods and Spriggit is when FormIDs collide.
+
+When new records are added, a FormID is claimed.   If two people working in parallel create a new record, then they both might claim the same FormID.   When merging their changes, this results in a duplicate FormID within the mod, which is not allowed.
+
+This will not result in a typical Git Merge Conflict, but it something to check for and fix after every merge.
+
+### Fixing FormID Collision
+Spriggit comes with tooling to detect and fix these FormID collisions.  It is recommended to do this after every merge.
+
+[:octicons-arrow-right-24: CLI Command](cli.md#formid-collision-fixing)
+
+!!! bug "Two Collisions Maximum"
+    The logic that Spriggit contains to handle FormID conflicts can only handle two records with a single FormID.  As such, collisions need to be handled immediately after each Git merge.

docs/spriggit-file.md

@@ -0,0 +1,24 @@
+# .spriggit File
+
+By default, the Translation Package and Version to use is set by the user when doing the translation call (either by UI or CMD).   In environments with multiple developers, though, this might be undesirable as each developer might choose different settings when working.
+
+A dedicated `.spriggit` file can be defined at or above the spriggit folder in the repository, which provides a centralized location that the package details can be set.  These specifications are automatically picked up and used by Spriggit, keeping the settings coordinated even with many developers.
+
+## Creating
+Right now the only way to make this file is by hand, but it is fairly trivial.
+
+Create a file named `.spriggit` with the desired content in this format:
+```
+{
+  "PackageName": "Spriggit.Yaml",
+  "Release": "Starfield",
+  "Version": "0.18"
+}
+```
+
+[:octicons-arrow-right-24: Game Releases](https://github.com/Mutagen-Modding/Mutagen/blob/dev/Mutagen.Bethesda.Kernel/GameRelease.cs)
+
+This file should be next to, or above the Spriggit mod folder(s) you want it to affect.
+
+## Updating
+To update to a different version, simply modify the file to the desired version, and then run any spriggit commands.

docs/translation-packages.md

@@ -0,0 +1,31 @@
+# Spriggit Translation Packages
+The logic for actually doing the translation is not housed or packaged directly with the CLI or UI.   Rather, the logic exists in NuGet packages that are downloaded and then used to do the translation.
+
+## Mechanics
+When Spriggit is asked to do a serialization from a Bethesda plugin file to text format, it takes the supplied Nuget package name and version and downloads that package.  It then uses the libraries within that package to do the translations.
+
+As such, a Spriggit CLI/UI can translate to/from many different translation formats/styles, rather than being bound to the translation logic that existed when the CLI/UI was built.
+
+## Reasoning
+This separation is an important aspect of keeping Spriggit flexible as record definitions evolve.   
+
+Especially early on during a game's release, the record definitions are constantly being upgraded, adjusted, and fixed.  The separation allows Spriggit to always grab the older version of a translation, and use that to deserialize text that contains older definitions.
+
+If very old versions get deserialized, the older nuget packages will be downloaded and used to read them.   And, if the user re-serializes them with the latest nuget packages, they will be "upgraded" to the latest text definitions.
+
+### Example
+Let's take a simple example of a typo.   Let's say `Haelth` was accidentally used as a field name in `v1.1` of Spriggit, and a plugin was serialized into text with that typo.
+Eventually someone notices, and fixes it to `Health` in `v1.2`.  How does the old file that contained `Haelth` get properly read anymore?
+
+It will be able to be read, because the original file will have been stamped with `v1.1`.  During deserialization of the file, Spriggit will see that and download that `v1.1` nuget package, and use that to read the file.   The `Haelth` field will be read in as expected by the `v1.1` package, yielding a proper esp output.
+
+## Customization
+Spriggit uses [Mutagen](https://github.com/Mutagen-Modding/Mutagen) systems under the hood, and leans on the [Mutagen.Bethesda.Serialization](https://github.com/Mutagen-Modding/Mutagen.Bethesda.Serialization) library to convert to/from Yaml and Json.
+
+One of the features of [Mutagen.Bethesda.Serialization](https://github.com/Mutagen-Modding/Mutagen.Bethesda.Serialization) is that it allows for customization of naming, file structure, and other similar things.   If you utilize this to make your own customization, you will need to upload the results to nuget.org for people to grab and use.
+
+More documentation will follow on how to upload your own customization package to Nuget so that it can be used by Spriggit.    For now, two packages exist "built in":
+- `Spriggit.Yaml.[GameName]`
+- `Spriggit.Json.[GameName]`
+
+These are what will be used to do any translations, unless the user specifies the name of a customization package they wish to use instead.

mkdocs.yml

@@ -57,4 +57,6 @@ nav:
   - Output: output.md
   - Installlation: installation.md
   - Command Line Interface: cli.md
-  - Translation Packages: translation-packages.md
+  - .spriggit File: spriggit-file.md
+  - Translation Packages: translation-packages.md
+  - Merge Conflicts: merge-conflicts.md