Documentation updates (#1395)

- Update README to point to https://sshnet.github.io/SSH.NET rather than the CHM file
- Add a CONTRIBUTING.md with some how-tos

For https://sshnet.github.io/SSH.NET:

- Use the repo README as the landing page to keep them in sync
- Combine the API-per-TFM pages to just one "API" page
- Add a couple more examples
- Add a GitHub link in the header.

Author: Rob-Hague

.gitignore

@@ -487,10 +487,5 @@ $RECYCLE.BIN/
 build/target/
 
 # Docs
-docfx/_site/**
-docfx/net462/**
-docfx/netstandard2.0/**
-docfx/netstandard2.1/**
-docfx/net6.0/**
-docfx/net7.0/**
-docfx/net8.0/**
+docfx/_site/
+docfx/api/

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+Contributions in the form of issues, pull requests (PRs) and discussions are welcome to this repository. Please consider that the library is currently maintained as a hobby by a small number of individuals. As such, depending on the weather, work, private lives etc., your PR may wait an indeterminate amount of time before being addressed. Generally speaking, the more targeted and better tested the change, the quicker it can be merged.
+
+## Building
+
+The library has no special requirements to build, other than an up-to-date .NET SDK, and can be built from within the IDE or with `dotnet build` at the command line.
+
+This repository also hosts the source for https://sshnet.github.io/SSH.NET/, which is built using [docfx](https://dotnet.github.io/docfx/index.html) and whose source files are in the `docfx/` directory. In order to build the site, install the docfx dotnet tool with `dotnet tool update -g docfx` and then run `docfx docfx/docfx.json --serve` from the root of the repository. When it completes, you should see e.g.
+
+```
+Serving "E:\github\SSH.NET\docfx\_site" on http://localhost:8080. Press Ctrl+C to shut down.
+```
+
+from which you can view the local version of the site. When making iterative changes, run `docfx docfx/docfx.json` from a separate command line and refresh the browser.
+
+## Testing
+
+The library has a test project for unit tests and a test project for integration tests. The latter uses [Testcontainers](https://dotnet.testcontainers.org/) which has a dependency on Docker. Practically, on Windows, an installation of Docker Desktop is all that is required, without any additional configuration. With Docker Desktop running, the integration tests can run like normal tests from within the IDE or with `dotnet test` at the command line.
+
+Code coverage information can be generated for all test projects at once or for individual test projects. From the root of the repository or from the individual test project directory, run `dotnet test --collect:"XPlat Code Coverage"`.
+
+The coverage information can be visualised using e.g. [ReportGenerator](https://reportgenerator.io/). Install the ReportGenerator dotnet tool with `dotnet tool update -g dotnet-reportgenerator-globaltool` and then run
+
+```
+reportgenerator -reports:**/coverage.cobertura.xml -targetdir:TestResults/CoverageReport -assemblyfilters:+Renci.SshNet
+```
+
+View the report by opening TestResults/CoverageReport/index.html in the browser.
+
+Before subsequent coverage collections, delete the previous collections with `git clean -fX test/` to prevent previous coverage files from being included in the subsequent generated report.
+
+## CI
+
+The repository makes use of continuous integration (CI) on [AppVeyor](https://ci.appveyor.com/project/drieseng/ssh-net/history) to validate builds and tests on PR branches and non-PR branches. At the time of writing, some tests can occasionally fail in CI due to a dependency on timing or a dependency on networking/socket code. If you see an existing test which is unrelated to your changes occasionally failing in CI but passing locally, you probably don't need to worry about it. If you see one of your newly-added tests failing, it is probably worth investigating why and whether it can be made more stable.
+
+## Good to know
+
+### TraceSource logging
+
+The Debug build of SSH.NET contains rudimentary logging functionality via `System.Diagnostics.TraceSource`. See `Renci.SshNet.Abstractions.DiagnosticAbstraction` for usage examples.
+
+### Wireshark
+
+Wireshark is able to dissect initial connection packets, such as key exchange, before encryption happens. Enter "ssh" as the display filter. See https://wiki.wireshark.org/SSH.md for more information.

README.md

@@ -14,15 +14,8 @@ 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)
-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.
-
+Documentation is hosted at https://sshnet.github.io/SSH.NET/. Currently (4/18/2020), the documentation is very sparse.
+Fortunately, there are a large number of [tests](https://github.com/sshnet/SSH.NET/tree/develop/test/) 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.  🤓
@@ -45,13 +38,15 @@ the missing test once you figure things out.  🤓
 ## Encryption Method
 
 **SSH.NET** supports the following encryption methods:
+* aes128-ctr
+* aes192-ctr
 * aes256-ctr
-* 3des-cbc
+* aes128-gcm<span></span>@openssh.com (.NET 6 and higher)
+* aes256-gcm<span></span>@openssh.com (.NET 6 and higher)
 * aes128-cbc
 * aes192-cbc
 * aes256-cbc
-* aes128-gcm<span></span>@openssh.com (.NET 6 and higher)
-* aes256-gcm<span></span>@openssh.com (.NET 6 and higher)
+* 3des-cbc
 * blowfish-cbc
 * twofish-cbc
 * twofish192-cbc
@@ -61,8 +56,6 @@ the missing test once you figure things out.  🤓
 * arcfour128
 * arcfour256
 * cast128-cbc
-* aes128-ctr
-* aes192-ctr
 
 ## Key Exchange Method
 
@@ -82,10 +75,10 @@ the missing test once you figure things out.  🤓
 ## 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
+* RSA in OpenSSL PEM ("BEGIN RSA PRIVATE KEY") and ssh.com ("BEGIN SSH2 ENCRYPTED PRIVATE KEY") format
+* DSA in OpenSSL PEM ("BEGIN DSA PRIVATE KEY") and ssh.com ("BEGIN SSH2 ENCRYPTED PRIVATE KEY") format
+* ECDSA 256/384/521 in OpenSSL PEM format ("BEGIN EC PRIVATE KEY")
+* ECDSA 256/384/521, ED25519 and RSA in OpenSSH key format ("BEGIN OPENSSH PRIVATE KEY")
 
 Private keys can be encrypted using one of the following cipher methods:
 * DES-EDE3-CBC
@@ -110,21 +103,20 @@ Private keys can be encrypted using one of the following cipher methods:
 ## 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-96
+* hmac-sha1
+* hmac-sha1-96
+* hmac-md5
+* hmac-md5-96
 * hmac-sha2-256-etm<span></span>@openssh.com
 * hmac-sha2-512-etm<span></span>@openssh.com
-
+* hmac-sha1-etm<span></span>@openssh.com
+* hmac-sha1-96-etm<span></span>@openssh.com
+* hmac-md5-etm<span></span>@openssh.com
+* hmac-md5-96-etm<span></span>@openssh.com
 
 ## Compression
 
@@ -174,6 +166,10 @@ using (var client = new SshClient("sftp.foo.com", "guest", "pwd"))
 }
 ```
 
+## Building the library
+
+The library has no special requirements to build, other than an up-to-date .NET SDK. See also [CONTRIBUTING.md](https://github.com/sshnet/SSH.NET/blob/develop/CONTRIBUTING.md).
+
 ## 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/docfx.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
   "metadata": [
     {
       "src": [
@@ -10,85 +11,7 @@
         }
       ],
       "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"
-      }
+      "output": "api"
     }
   ],
   "build": {
@@ -110,7 +33,8 @@
     "output": "_site",
     "template": [
       "default",
-      "modern"
+      "modern",
+      "template"
     ],
     "globalMetadata": {
       "_appName": "SSH.NET",