Merge pull request #192 from SceneGate/feature/new-docs

✨📚 New documentation website and project name re-meaning

.config/dotnet-tools.json

@@ -7,6 +7,12 @@
       "commands": [
         "dotnet-cake"
       ]
+    },
+    "docfx": {
+      "version": "2.70.3",
+      "commands": [
+        "docfx"
+      ]
     }
   }
 }

.github/workflows/build-and-release.yml

@@ -37,7 +37,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: "Build, test and stage"
-        run: dotnet cake --target=Stage-Artifacts --configuration=Release --verbosity=diagnostic
+        run: dotnet cake --target=Stage-Artifacts-NewDocs --configuration=Release --verbosity=diagnostic
 
       - name: "Publish test results"
         uses: actions/upload-artifact@v2

.gitignore

@@ -11,9 +11,5 @@ artifacts/
 # Cake
 tools/*
 
-# Docs
-docs/_site/
-docs/api/
-
 # Benchmarks
 BenchmarkDotNet.Artifacts/

.vscode/settings.json

@@ -17,10 +17,12 @@
         "Conv",
         "cref",
         "Dependee",
+        "Ekona",
         "Diagnoser",
         "finalizer",
         "msgctxt",
         "Msgid",
         "typeparam"
     ],
+    "dotnet.defaultSolution": "src/Yarhl.sln",
 }

README.md

@@ -1,55 +1,117 @@
-# Yarhl: Yet Another ROM Hacking Library [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://choosealicense.com/licenses/mit/)
+# Yarhl, A format ResearcH Library [![awesomeness](https://img.shields.io/badge/SceneGate-awesome%20%F0%9F%95%B6-blue?logo=csharp)](https://github.com/SceneGate)
 
 ![Yarhl Logo](https://raw.githubusercontent.com/SceneGate/Yarhl/develop/docs/images/logo.png)
 
-**Yarhl** is a library for _ROM Hacking_ and fan-translation projects. It
-provides a virtual file system, file format and format conversion features and
-plugin support. It's built in C# / .NET and works in Windows, Linux and Mac OS
-X.
-
-<!-- prettier-ignore -->
-| NuGet              | [![Yarhl](https://img.shields.io/nuget/v/Yarhl?label=Yarhl)](https://www.nuget.org/packages/Yarhl) [![Yarhl.Media.Text](https://img.shields.io/nuget/v/Yarhl.Media.Text?label=Yarhl.Media.Text)](https://www.nuget.org/packages/Yarhl.Media.Text) |
-| ------------------ | ------ |
-| **Build & Test**   | ![Build and release](https://github.com/SceneGate/Yarhl/workflows/Build%20and%20release/badge.svg?branch=develop) |
-| **Quality report** | [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/2919/badge)](https://bestpractices.coreinfrastructure.org/projects/2919) |
-
-## Documentation
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <a href="https://www.nuget.org/packages?q=Yarhl">
+    <img alt="Stable version" src="https://img.shields.io/nuget/v/Yarhl?label=Stable" />
+  </a>
+  &nbsp;
+  <a href="https://dev.azure.com/SceneGate/SceneGate/_packaging?_a=feed&feed=SceneGate-Preview">
+    <img alt="GitHub commits since latest release (by SemVer)" src="https://img.shields.io/github/commits-since/SceneGate/Yarhl/latest?sort=semver" />
+  </a>
+  &nbsp;
+  <a href="https://github.com/SceneGate/Yarhl/workflows/Build%20and%20release">
+    <img alt="Build and release" src="https://github.com/SceneGate/Yarhl/workflows/Build%20and%20release/badge.svg?branch=develop" />
+  </a>
+  &nbsp;
+  <a href="https://bestpractices.coreinfrastructure.org/projects/2919">
+    <img alt="CII Best Practices" src="https://bestpractices.coreinfrastructure.org/projects/2919/badge" />
+  </a>
+  &nbsp;
+  <a href="https://choosealicense.com/licenses/mit/">
+    <img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat" />
+  </a>
+  &nbsp;
+</p>
+
+**Yarhl** is a set of libraries that helps to **implement and convert file
+formats**. It provides a virtual file system, format conversion APIs, full
+featured binary IO and plugin support to support common formats. It's built in
+**C# / .NET** and works in any OS that supports the .NET runtime.
+
+- :books: **Format implementation** architecture and guidelines
+- :recycle: **Format conversion** API
+- :open_file_folder: **Virtual file system** with format transformations
+- :1234: **Enhanced binary IO API**
+  - Custom `Stream` with **sub-stream supports** (memory and disk efficient!)
+  - Full feature binary and text readers and writers
+  - Simple binary (de)serializer by attributes in the model.
+- :page_with_curl: Standard text formats
+  - Industry-standard localization format: **GNU gettext PO**
+  - Table text replacements
+  - **Common encodings**: euc-jp, token-escaped encoding
+  - **API for simple encoding implementations**
+
+## Get started
+
+Check out the [documentation site](https://scenegate.github.io/Yarhl/index.html)
+to start learning the power of _Yarhl_.
 
 Feel free to ask any question in the
-[project Discussion site!](https://github.com/SceneGate/Yarhl/discussions).
-
-Check our on-line API overview:
-[Yarhl in a nutshell](https://scenegate.github.io/Yarhl/guides/Yarhl-nutshell.html)
-and the complete API documentation
-[here](https://scenegate.github.io/Yarhl/api/Yarhl.html).
+[project discussions](https://github.com/SceneGate/Yarhl/discussions).
 
-## Install
+## Usage
 
-Stable releases are available from nuget.org:
+This project provides the following libraries as NuGet packages (via nuget.org).
+The libraries support the latest version of .NET and its LTS.
 
-- [Yarhl](https://www.nuget.org/packages/Yarhl)
-- [Yarhl.Media.Text](https://www.nuget.org/packages/Yarhl.Media.Text)
+- [![Yarhl](https://img.shields.io/nuget/v/Yarhl?label=Yarhl&logo=nuget)](https://www.nuget.org/packages/Yarhl):
+  core, format conversion, file system and binary reading / writing (IO).
+- [![Yarhl.Media.Text](https://img.shields.io/nuget/v/Yarhl.Media.Text?label=Yarhl.Media.Text&logo=nuget)](https://www.nuget.org/packages/Yarhl.Media.Text):
+  text formats (Po) and encodings.
+- [![Yarhl.Plugins](https://img.shields.io/nuget/v/Yarhl.Plugins?label=Yarhl.Plugins&logo=nuget)](https://www.nuget.org/packages/Yarhl.Plugins):
+  discover formats and converters from .NET assemblies.
 
-The libraries only support the latest version of .NET and its LTS (.NET 6).
-
-Preview releases can be found in this
+**Preview releases** can be found in this
 [Azure DevOps package repository](https://dev.azure.com/SceneGate/SceneGate/_packaging?_a=feed&feed=SceneGate-Preview).
 To use a preview release, create a file `nuget.config` in the same directory of
-your solution (.sln) file with the following content:
+your solution file (.sln) with the following content:
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
 <configuration>
   <packageSources>
+    <clear/>
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
     <add key="SceneGate-Preview" value="https://pkgs.dev.azure.com/SceneGate/SceneGate/_packaging/SceneGate-Preview/nuget/v3/index.json" />
   </packageSources>
+  <packageSourceMapping>
+    <packageSource key="nuget.org">
+      <package pattern="*" />
+    </packageSource>
+    <packageSource key="SceneGate-Preview">
+      <package pattern="Yarhl*" />
+    </packageSource>
+  </packageSourceMapping>
 </configuration>
 ```
 
-## Build
+Then restore / install as usual via Visual Studio, Rider or command-line. You
+may need to restart Visual Studio for the changes to apply.
+
+## Showcase
+
+Some cool projects built with _Yarhl_:
 
-The project requires to build .NET 6.0 SDK and .NET Framework 4.8 or latest
-Mono. If you open the project with VS Code and you did install the
+- [**Texim**](https://github.com/SceneGate/Texim): experimental API for image
+  file formats.
+- [**Ekona**](https://scenegate.github.io/Ekona/): support Nintendo DS file
+  formats.
+- [**Lemon**](https://scenegate.github.io/Lemon/): support Nintendo 3DS file
+  formats.
+- [**LayTea**](https://www.pleonex.dev/LayTea/): modding tools for _Professor
+  Layton_ games.
+- [**Attack of Friday Monsters tools**](https://github.com/pleonex/AttackFridayMonsters):
+  modding tools for _Attack of the Friday Monsters_ game.
+- [**Metatron**](https://github.com/TraduSquare/Metatron): translation framework
+  for _Shin Megami Tensei_ saga games.
+
+## Contributing
+
+The repository requires to build .NET 6.0 SDK and .NET Framework 4.8 or latest
+Mono (for DocFX). If you open the project with VS Code and you did install the
 [VS Code Remote Containers](https://code.visualstudio.com/docs/remote/containers)
 extension, you can have an already pre-configured development environment with
 Docker or Podman.
@@ -60,7 +122,7 @@ To build, test and generate artifacts run:
 # Only required the first time
 dotnet tool restore
 
-# Default target is Stage-Artifacts
+# Default target is "Default" that builds, runs tests, build doc and create the NuGets
 dotnet cake
 ```
 
@@ -69,3 +131,13 @@ To just build and test quickly, run:
 ```sh
 dotnet cake --target=BuildTest
 ```
+
+Additionally you can use _Visual Studio_ or _JetBrains Rider_ as any other .NET
+project.
+
+To contribute follow the [contributing guidelines](CONTRIBUTING.md).
+
+## License
+
+The software is licensed under the terms of the
+[MIT license](https://choosealicense.com/licenses/mit/).

build.cake

@@ -11,9 +11,31 @@ Task("Define-Project")
     info.AddTestProjects("Yarhl.UnitTests");
     info.AddTestProjects("Yarhl.IntegrationTests");
 
+    info.ChangelogFile = "docs/articles/Changelog.md";
+
     info.PreviewNuGetFeed = "https://pkgs.dev.azure.com/SceneGate/SceneGate/_packaging/SceneGate-Preview/nuget/v3/index.json";
 });
 
+Task("DocFx-BuildDoc")
+    .Does<BuildInfo>(info =>
+{
+    if (!FileExists(info.DocFxFile)) {
+        Warning("There isn't documentation.");
+        return;
+    }
+
+    string args = $"-o {info.ArtifactsDirectory}/_site";
+    if (info.WarningsAsErrors) {
+        args += " --warningsAsErrors";
+    }
+
+    DotNetTool($"docfx {info.DocFxFile} {args}");
+
+    Zip(
+        $"{info.ArtifactsDirectory}/_site",
+        $"{info.ArtifactsDirectory}/docs.zip");
+});
+
 Task("Prepare-IntegrationTests")
     .Description("Prepare the integration tests by copying an example of DLL")
     .IsDependeeOf("Test")
@@ -53,7 +75,13 @@ public IEnumerable<string> GetTargetFrameworks(string projectPath)
 }
 
 Task("Default")
-    .IsDependentOn("Stage-Artifacts");
+    .IsDependentOn("Stage-Artifacts-NewDocs");
+
+Task("Stage-Artifacts-NewDocs")
+    .IsDependentOn("BuildTest")
+    .IsDependentOn("DocFx-BuildDoc")
+    .IsDependentOn("Pack-Libs")
+    .IsDependentOn("Pack-Apps");
 
 string target = Argument("target", "Default");
 RunTarget(target);

docs/.gitignore

@@ -0,0 +1,12 @@
+###############
+#    folder   #
+###############
+/**/DROP/
+/**/TEMP/
+/**/packages/
+/**/bin/
+/**/obj/
+_site
+
+# DrawIO
+.$*.drawio*

docs/api/.gitignore

@@ -0,0 +1,5 @@
+###############
+#  temp file  #
+###############
+*.yml
+.manifest

docs/articles/core/binary/attr-serialization.md

@@ -0,0 +1,3 @@
+# (De)serialization via attributes
+
+TODO

docs/articles/core/binary/binaryformat.md

@@ -0,0 +1,3 @@
+# Binary format
+
+TODO

docs/articles/core/binary/binaryreader-writer.md

@@ -0,0 +1,3 @@
+# Binary reader and writer
+
+TODO

docs/articles/core/binary/custom-streams.md

@@ -0,0 +1,3 @@
+# Custom streams
+
+TODO