Added support for GitHub pages using docfx

[jscarle]

This PR adds support for publishing documentation as GitHub pages using docfx.

After this PR is merged, three things need to be done for setup to be completed.

1) GitHub pages must be activated for this repository by navigating to Settings => Pages and changing the Build and deployment source to GitHub Actions here (https://github.com/sshnet/SSH.NET/settings/pages)

2) From the main repository page (https://github.com/sshnet/SSH.NET) on the About gear for the settings:

The option Use your GitHub Pages website should be checked:

3) The GitHub Action for Docs must be manually run at least once (https://github.com/sshnet/SSH.NET/actions/workflows/docs.yml):

Once the docs have been published once, they will be automatically published everytime develop is merged with master.

[jscarle]

@WojciechNagorski Ready for review and merge. Let me know if you have any questions!

[jscarle]

@WojciechNagorski @Rob-Hague This is now ready to merge and synced with develop.

[jscarle]

Thanks @jscarle. I don't know anything about it but it looks nice and simple. Two questions:

1. Is it possible to preview the output without merging, either locally or on GH?

Certainly! From the root of the repository, simply run the two commands from the pipeline:

dotnet tool update -g docfx
docfx ./docfx/docfx.json

That will produce the site in ./docfx/_site, which as you'll see, is just a plain HTML site. You can view it by opening index.html.

2. Is it possible to have the additional docs (features.md, foreward.md, usage.md) without duplicating from the README? E.g. including snippets of markdown (or something). If not, can we just directly use the README for now to avoid having to update in multiple places?

Sure, we can do whatever we'd like with the additional content of the site. I just split up the README as a starting point. I could also work into a way to include the README directly. Though the objective would be to simplify the README and instead grow this site.

[Rob-Hague]

On index.html I don't see anything to click on to get to the code. Does that get hooked up automatically?

For the additional content, I'll leave it up to you if you expect the site and the readme to diverge in the near future. If they are going to stay equal for a while, then having just one place to update would be nicer from a maintenance perspective if it's easy to do.

[jscarle]

On index.html I don't see anything to click on to get to the code. Does that get hooked up automatically?

Sorry about that, I forgot. You have to do:

docfx ./docfx/docfx.json --serve

Then, at the end you should see:

Serving "E:\github\SSH.NET\docfx\_site" on http://localhost:8080. Press Ctrl+C to shut down.

It runs a little bit of JavaScript, so that's probably why it won't completely load locally without running serve.

[Rob-Hague]

http://sshnet.github.io/SSH.NET/

[jscarle]

Good stuff!

[scott-xu]

Need to update https://github.com/sshnet/SSH.NET/blob/develop/docfx/docs/foreword.md/