Added support for GitHub pages using docfx (#1358)

* Added support for GitHub pages using docfx

* Fixed StyleCop warning.

* Fixed other StyleCop warnings.

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Docs
+
+on:
+  push:
+    branches: ["master"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Setup .NET 8.0
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 8.x
+
+      - name: Setup docfx
+        run: dotnet tool update -g docfx
+
+      - name: Build documentation
+        run: docfx ./docfx/docfx.json
+
+      - name: Upload documentation
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './docfx/_site'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -485,3 +485,12 @@ $RECYCLE.BIN/
 
 # Build outputs
 build/target/
+
+# Docs
+docfx/_site/**
+docfx/net462/**
+docfx/netstandard2.0/**
+docfx/netstandard2.1/**
+docfx/net6.0/**
+docfx/net7.0/**
+docfx/net8.0/**

README.md

@@ -7,11 +7,13 @@ SSH.NET is a Secure Shell (SSH-2) library for .NET, optimized for parallelism.
 [![Build status](https://ci.appveyor.com/api/projects/status/ih77qu6tap3o92gu/branch/develop?svg=true)](https://ci.appveyor.com/api/projects/status/ih77qu6tap3o92gu/branch/develop)
 
 ## Introduction
+
 This project was inspired by **Sharp.SSH** library which was ported from java and it seems like was not supported
 for quite some time. This library is a complete rewrite, without any third party dependencies, using parallelism
 to achieve the best performance possible.
 
 ## Documentation
+
 There is MSDN-style class documentation in a .chm file for each release, which you can find in the Assets section
 of the [latest release](https://github.com/sshnet/SSH.NET/releases/latest) page.  Please note that you will need
 to [right-click and "unblock"](https://support.microsoft.com/en-us/help/2021383/some-chm-files-may-not-render-properly-on-windows-vista-and-windows-7)
@@ -26,6 +28,7 @@ invited to read the source, Luke, and highly encouraged to generate a pull reque
 the missing test once you figure things out.  🤓
 
 ## Features
+
 * Execution of SSH command using both synchronous and asynchronous methods
 * Return command execution exit status and other information 
 * Provide SFTP functionality for both synchronous and asynchronous operations
@@ -121,6 +124,7 @@ Private keys can be encrypted using one of the following cipher methods:
 * hmac-sha2-512-etm<span></span>@openssh.com
 
 ## Framework Support
+
 **SSH.NET** supports the following target frameworks:
 * .NETFramework 4.6.2 (and higher)
 * .NET Standard 2.0 and 2.1

docfx/docfx.json

@@ -0,0 +1,124 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "src": "../src",
+          "files": [
+            "**/*.csproj"
+          ]
+        }
+      ],
+      "outputFormat": "apiPage",
+      "dest": "net462",
+      "properties": {
+        "TargetFramework": "net462"
+      }
+    },
+    {
+      "src": [
+        {
+          "src": "../src",
+          "files": [
+            "**/*.csproj"
+          ]
+        }
+      ],
+      "outputFormat": "apiPage",
+      "dest": "netstandard2.0",
+      "properties": {
+        "TargetFramework": "netstandard2.0"
+      }
+    },
+    {
+      "src": [
+        {
+          "src": "../src",
+          "files": [
+            "**/*.csproj"
+          ]
+        }
+      ],
+      "outputFormat": "apiPage",
+      "dest": "netstandard2.1",
+      "properties": {
+        "TargetFramework": "netstandard2.1"
+      }
+    },
+    {
+      "src": [
+        {
+          "src": "../src",
+          "files": [
+            "**/*.csproj"
+          ]
+        }
+      ],
+      "outputFormat": "apiPage",
+      "dest": "net6.0",
+      "properties": {
+        "TargetFramework": "net6.0"
+      }
+    },
+    {
+      "src": [
+        {
+          "src": "../src",
+          "files": [
+            "**/*.csproj"
+          ]
+        }
+      ],
+      "outputFormat": "apiPage",
+      "dest": "net7.0",
+      "properties": {
+        "TargetFramework": "net7.0"
+      }
+    },
+    {
+      "src": [
+        {
+          "src": "../src",
+          "files": [
+            "**/*.csproj"
+          ]
+        }
+      ],
+      "outputFormat": "apiPage",
+      "dest": "net8.0",
+      "properties": {
+        "TargetFramework": "net8.0"
+      }
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": "**/*.{md,yml}",
+        "exclude": [
+          "_site/**"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      }
+    ],
+    "output": "_site",
+    "template": [
+      "default",
+      "modern"
+    ],
+    "globalMetadata": {
+      "_appName": "SSH.NET",
+      "_appTitle": "SSH.NET - A Secure Shell (SSH) library for .NET, optimized for parallelism",
+      "_appLogoPath": "images/logo.png",
+      "_appFaviconPath": "images/icon.png",
+      "_appFooter": "Copyright (c) Renci, Oleg Kapeljushnik, Gert Driesen and contributors",
+      "_enableSearch": true
+    }
+  }
+}

docfx/docs/features.md

@@ -0,0 +1,102 @@
+# Features
+
+* Execution of SSH command using both synchronous and asynchronous methods
+* Return command execution exit status and other information
+* Provide SFTP functionality for both synchronous and asynchronous operations
+* Provides SCP functionality
+* Provide status report for upload and download sftp operations to allow accurate progress bar implementation
+* Remote, dynamic and local port forwarding
+* Shell/Terminal implementation
+* Specify key file pass phrase
+* Use multiple key files to authenticate
+* Supports publickey, password and keyboard-interactive authentication methods
+* Supports two-factor or higher authentication
+* Supports SOCKS4, SOCKS5 and HTTP Proxy
+
+## Encryption Method
+
+**SSH.NET** supports the following encryption methods:
+* aes256-ctr
+* 3des-cbc
+* aes128-cbc
+* aes192-cbc
+* aes256-cbc
+* blowfish-cbc
+* twofish-cbc
+* twofish192-cbc
+* twofish128-cbc
+* twofish256-cbc
+* arcfour
+* arcfour128
+* arcfour256
+* cast128-cbc
+* aes128-ctr
+* aes192-ctr
+
+## Key Exchange Method
+
+**SSH.NET** supports the following key exchange methods:
+* curve25519-sha256
+* curve25519-sha256<span></span>@libssh.org
+* ecdh-sha2-nistp256
+* ecdh-sha2-nistp384
+* ecdh-sha2-nistp521
+* diffie-hellman-group-exchange-sha256
+* diffie-hellman-group-exchange-sha1
+* diffie-hellman-group16-sha512
+* diffie-hellman-group14-sha256
+* diffie-hellman-group14-sha1
+* diffie-hellman-group1-sha1
+
+## Public Key Authentication
+
+**SSH.NET** supports the following private key formats:
+* RSA in OpenSSL PEM and ssh.com format
+* DSA in OpenSSL PEM and ssh.com format
+* ECDSA 256/384/521 in OpenSSL PEM format
+* ECDSA 256/384/521, ED25519 and RSA in OpenSSH key format
+
+Private keys can be encrypted using one of the following cipher methods:
+* DES-EDE3-CBC
+* DES-EDE3-CFB
+* DES-CBC
+* AES-128-CBC
+* AES-192-CBC
+* AES-256-CBC
+
+## Host Key Algorithms
+
+**SSH.NET** supports the following host key algorithms:
+* ssh-ed25519
+* ecdsa-sha2-nistp256
+* ecdsa-sha2-nistp384
+* ecdsa-sha2-nistp521
+* rsa-sha2-512
+* rsa-sha2-256
+* ssh-rsa
+* ssh-dss
+
+## Message Authentication Code
+
+**SSH.NET** supports the following MAC algorithms:
+* hmac-md5
+* hmac-md5-96
+* hmac-sha1
+* hmac-sha1-96
+* hmac-sha2-256
+* hmac-sha2-256-96
+* hmac-sha2-512
+* hmac-sha2-512-96
+* hmac-md5-etm<span></span>@openssh.com
+* hmac-md5-96-etm<span></span>@openssh.com
+* hmac-sha1-etm<span></span>@openssh.com
+* hmac-sha1-96-etm<span></span>@openssh.com
+* hmac-sha2-256-etm<span></span>@openssh.com
+* hmac-sha2-512-etm<span></span>@openssh.com
+
+## Framework Support
+
+**SSH.NET** supports the following target frameworks:
+* .NETFramework 4.6.2 (and higher)
+* .NET Standard 2.0 and 2.1
+* .NET 6 (and higher)

docfx/docs/foreword.md

@@ -0,0 +1,14 @@
+# Foreword
+
+There is MSDN-style class documentation in a .chm file for each release, which you can find in the Assets section
+of the [latest release](https://github.com/sshnet/SSH.NET/releases/latest) page.  Please note that you will need
+to [right-click and "unblock"](https://support.microsoft.com/en-us/help/2021383/some-chm-files-may-not-render-properly-on-windows-vista-and-windows-7)
+the CHM file after you download it.
+
+Currently (4/18/2020), the documentation is very sparse.  Fortunately, there are a large number of tests in
+[Renci.SshNet.Tests](https://github.com/sshnet/SSH.NET/tree/develop/test/Renci.SshNet.Tests) that demonstrate
+usage with working code.
+
+If the test for the functionality you would like to see documented is not complete, then you are cordially
+invited to read the source, Luke, and highly encouraged to generate a pull request for the implementation of
+the missing test once you figure things out.  🤓

docfx/docs/toc.yml

@@ -0,0 +1,6 @@
+- name: Foreword
+  href: foreword.md
+- name: Features
+  href: features.md
+- name: Usage
+  href: usage.md

docfx/docs/usage.md

@@ -0,0 +1,34 @@
+# Usage
+
+## Multi-factor authentication
+
+Establish a SFTP connection using both password and public-key authentication:
+
+```cs
+var connectionInfo = new ConnectionInfo("sftp.foo.com",
+                                        "guest",
+                                        new PasswordAuthenticationMethod("guest", "pwd"),
+                                        new PrivateKeyAuthenticationMethod("rsa.key"));
+using (var client = new SftpClient(connectionInfo))
+{
+    client.Connect();
+}
+
+```
+
+## Verify host identify
+
+Establish a SSH connection using user name and password, and reject the connection if the fingerprint of the server does not match the expected fingerprint:
+
+```cs
+string expectedFingerPrint = "LKOy5LvmtEe17S4lyxVXqvs7uPMy+yF79MQpHeCs/Qo";
+
+using (var client = new SshClient("sftp.foo.com", "guest", "pwd"))
+{
+    client.HostKeyReceived += (sender, e) =>
+        {
+            e.CanTrust = expectedFingerPrint.Equals(e.FingerPrintSHA256);
+        };
+    client.Connect();
+}
+```

docfx/index.md

@@ -0,0 +1,19 @@
+---
+_layout: landing
+---
+
+SSH.NET is a Secure Shell (SSH-2) library for .NET, optimized for parallelism.
+
+[![Version](https://img.shields.io/nuget/vpre/SSH.NET.svg)](https://www.nuget.org/packages/SSH.NET)
+[![NuGet download count](https://img.shields.io/nuget/dt/SSH.NET.svg)](https://www.nuget.org/packages/SSH.NET)
+[![Build status](https://ci.appveyor.com/api/projects/status/ih77qu6tap3o92gu/branch/develop?svg=true)](https://ci.appveyor.com/api/projects/status/ih77qu6tap3o92gu/branch/develop)
+
+## Introduction
+
+This project was inspired by **Sharp.SSH** library which was ported from java and it seems like was not supported
+for quite some time. This library is a complete rewrite, without any third party dependencies, using parallelism
+to achieve the best performance possible.
+
+## Supporting SSH.NET
+
+Do you or your company rely on **SSH.NET** in your projects? If you want to encourage us to keep on going and show us that you appreciate our work, please consider becoming a [sponsor](https://github.com/sponsors/sshnet) through GitHub Sponsors.

docfx/toc.yml

@@ -0,0 +1,14 @@
+- name: Docs
+  href: docs/
+- name: .NET Framework 4.6.2
+  href: net462/
+- name: .NET Standard 2.0
+  href: netstandard2.0/
+- name: .NET Standard 2.1
+  href: netstandard2.1/
+- name: .NET 6.0
+  href: net6.0/
+- name: .NET 7.0
+  href: net7.0/
+- name: .NET 8.0
+  href: net8.0/

stylecop.json

@@ -3,7 +3,8 @@
     "settings": {
         "documentationRules": {
             "xmlHeader": false,
-            "documentInternalElements": false
+            "documentInternalElements": false,
+            "fileNamingConvention": "metadata"
         },
         "layoutRules": {
             "newlineAtEndOfFile": "require"