Add automatically generated documentation

StefanGreve · StefanGreve · commit fd7206f3f300 · 2024-07-30T21:56:55.000+02:00
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,46 @@
+name: Docs
+
+on:
+  push:
+    branches: [ master ]
+  workflow_dispatch:
+
+env:
+  DOTNET_VERSION: '8.0.x'
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  actions: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  publish-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Dotnet Setup
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: ${{ env.DOTNET_VERSION }}
+
+    - run: dotnet tool update -g docfx
+    - run: docfx docs/docfx.json
+
+    - name: Upload Artifact
+      uses: actions/upload-pages-artifact@v3.0.1
+      with:
+        path: docs/_site
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4
diff --git a/AdvancedSystems.Security/Common/Bytes.cs b/AdvancedSystems.Security/Common/Bytes.cs
@@ -49,7 +49,7 @@ public static string ToString(this byte[] array, Format format)
     ///     This method exposes the internal state of <see cref="SecureString"/> through marshaling.
     ///     It is no longer recommended to use the <see cref="SecureString"/> for new development on .NET Core projects.
     /// </remarks>
-    /// <exception cref="ArgumentNullException">Raised if <paramref name="secureString"/> is <seealso cref="null"/>.</exception>
+    /// <exception cref="ArgumentNullException">Raised if <paramref name="secureString"/> is <c>null</c>.</exception>
     /// <seealso href="https://github.com/dotnet/platform-compat/blob/master/docs/DE0001.md"/>
     [Obsolete]
     public static byte[] GetBytes(this SecureString secureString, Encoding? encoding = null)
diff --git a/AdvancedSystems.Security/Cryptography/Hash.cs b/AdvancedSystems.Security/Cryptography/Hash.cs
@@ -7,9 +7,6 @@ namespace AdvancedSystems.Security.Cryptography;
 /// <summary>
 ///     Implements cryptographic hash algorithms.
 /// </summary>
-/// <remarks>
-///     Use the <see cref="Bytes.AreEqual(byte[], byte[])"/> function for hash comparisons.
-/// </remarks>
 public static class Hash
 {
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
diff --git a/docs/docfx.json b/docs/docfx.json
@@ -0,0 +1,54 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "src": "../AdvancedSystems.Security",
+          "files": [
+            "**/*.csproj"
+          ]
+        }
+      ],
+      "dest": "api",
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "**/*.{md,yml}"
+        ],
+        "exclude": [
+          "_site/**"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      }
+    ],
+    "output": "_site",
+    "template": [
+      "default",
+      "modern"
+    ],
+    "globalMetadata": {
+      "_appName": "AdvancedSystems.Security",
+      "_appTitle": "AdvancedSystems.Security",
+      "_appFaviconPath": "images/favicon.svg",
+      "_appLogoPath": "images/adv-logo-brand.svg",
+      "_appFooter": "Copyright © Advanced Systems 2024",
+      "_disableContribution": false,
+      "_gitContribute": {
+        "repo": "https://github.com/Advanced-Systems/security"
+      },
+      "_enableSearch": true,
+      "pdf": false
+    }
+  }
+}
diff --git a/docs/docs/changelog.md b/docs/docs/changelog.md
@@ -0,0 +1,3 @@
+# Changelog
+
+TODO
diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md
@@ -0,0 +1,3 @@
+# Getting Started
+
+TODO
diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md
@@ -0,0 +1,3 @@
+# Introduction
+
+TODO
diff --git a/docs/docs/toc.yml b/docs/docs/toc.yml
@@ -0,0 +1,6 @@
+- name: Introduction
+  href: introduction.md
+- name: Getting Started
+  href: getting-started.md
+- name: Changelog
+  href: changelog.md
diff --git a/docs/images/adv-logo-brand.svg b/docs/images/adv-logo-brand.svg
diff --git a/docs/images/favicon.svg b/docs/images/favicon.svg
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,8 @@
+---
+_layout: landing
+---
+
+# Advanced Systems Security
+
+This library provides classes and services for symmetric and asymmetric standard
+cryptographic algorithms based on the .NET cryptography system.
diff --git a/docs/toc.yml b/docs/toc.yml
@@ -0,0 +1,4 @@
+- name: Docs
+  href: docs/
+- name: API
+  href: api/
diff --git a/readme.md b/readme.md
@@ -6,20 +6,51 @@
 
 <h1 align="center">Advanced Systems Security</h1>
 
+[![Unit Tests](https://github.com/Advanced-Systems/security/actions/workflows/dotnet-tests.yml/badge.svg)](https://github.com/Advanced-Systems/security/actions/workflows/dotnet-tests.yml)
+[![CodeQL](https://github.com/Advanced-Systems/security/actions/workflows/codeql.yml/badge.svg)](https://github.com/Advanced-Systems/security/actions/workflows/codeql.yml)
+[![Docs](https://github.com/Advanced-Systems/security/actions/workflows/docs.yml/badge.svg)](https://github.com/Advanced-Systems/security/actions/workflows/docs.yml)
+
+## About
+
 The `AdvancedSystems.Security` library provides classes and services for symmetric and
 asymmetric standard cryptographic algorithms based on the .NET cryptography system.
 
+```powershell
+dotnet add package AdvancedSystems.Security
+```
+
+The changelog for this package are available [here](https://advanced-systems.github.io/security/docs/changelog.html).
+
+Package consumers can also use the symbols published to nuget.org symbol server by adding <https://symbols.nuget.org/download/symbols>
+to their symbol sources in Visual Studio, which allows stepping into package code in the Visual Studio debugger. See
+[Specify symbol (.pdb) and source files in the Visual Studio debugger](https://learn.microsoft.com/en-us/visualstudio/debugger/specify-symbol-dot-pdb-and-source-files-in-the-visual-studio-debugger)
+for details on that process.
+
+Additionally, this project also supports [source link technology](https://learn.microsoft.com/en-us/dotnet/standard/library-guidance/sourcelink)
+for debugging .NET assemblies.
+
 ## Development Environment
 
-This project uses [stryker](https://stryker-mutator.io/) for mutation testing, which is
-setup to be installed with
+Run test suite:
 
 ```powershell
-dotnet tool restore --configfile .\AdvancedSystems.Security\nuget.config
+dotnet test .\AdvancedSystems.Core.Tests\ --no-logo
+```
+
+In addition to unit testing, this project also uses stryker for mutation testing, which is setup to be installed with
+
+```powershell
+dotnet tool restore --configfile nuget.config
 ```
 
 Run stryker locally:
 
 ```powershell
 dotnet stryker
-```
+```
+
+Build and serve documentation locally (`http://localhost:8080`):
+
+```powershell
+docfx .\docs\docfx.json --serve
+```
