Migrate docs to DocFX

[gumbarros]

Fixes

Issue #145

Description

This PR migrates the contents from the GitHub wiki without any changes (except the links) to DocFX.

To check by yourself

dotnet tool install -g docfx

cd docs

docfx metadata

docfx build --serve

Showcase

Additional comments

If you don't like the layout, we can use any of these themes or create one from scratch like NCalc.

I liked the result, I think this will greatly improve the SEO of the project and the public API section is very welcome for undocumented classes. I also think there is a lot of work to do, like better docs for some providers, re-work the menu and docs for provider agnostic usage like listing files, rename, create folder behavior etc.

[gumbarros]

Also, I did not create any CI in this PR because I dont know if you will approve, but can be easily configured like this

[robinrodricks]

Looks good. I'll look thru the themes later. Can we rename the "Articles" button to "Wiki". And where will it be hosted? I would like it to be hosted on github itself using static sites as I would not like to redirect traffic to a 3rd party.

[gumbarros]

Looks good. I'll look thru the themes later. Can we rename the "Articles" button to "Wiki". And where will it be hosted? I would like it to be hosted on github itself using static sites as I would not like to redirect traffic to a 3rd party.

Sure, and the CI pipeline I share will publish to

yourusername.github.io/fluentstorage

Except if you create a GitHub org for FluentStorage, then it will be fluentstorage.github.io/fluentstorage

[robinrodricks]

Hi, what does the PR do? It generates HTML? Where is the HTML placed? I will need to make another repo for fluentstorage as a github website and copy those HTML into that repo.

[gumbarros]

Hi, what does the PR do? It generates HTML? Where is the HTML placed? I will need to make another repo for fluentstorage as a github website and copy those HTML into that repo.

No. I think you understand the concept incorrectly.

All is versioned as markdown at the repo in /docs.

When you commit on main, develop or any CI trigger that you like happens, docfx will convert at publish time all markdown into HTML and deploy at GitHub Pages.

It's also possible to have a separate repo if you like, but never HTML, only markdown.

Public API is generated automatically with only a small config at docfx.json, also converted to HTML at publish time.

So basically its like a markdown compiler and HTML files are the non-versioned files.

[robinrodricks]

It's also possible to have a separate repo if you like, but never HTML, only markdown

I understand completely. But for github websites, we need to push the HTML + CSS output into a new repo otherwise we cannot have a github public site. So we need to configure the publish dir so that it can publish into another repo.

Public API is generated automatically with only a small config

I can see that in the csproj and docfx.

So basically its like a markdown compiler

How did u extract the github wiki as markdown? What's the command for that?

[gumbarros]

I understand completely. But for github websites, we need to push the HTML + CSS output into a new repo otherwise we cannot have a github public site. So we need to configure the publish dir so that it can publish into another repo.

With GitHub actions there is no need, I will commit a CI file so you can check.

How did u extract the github wiki as markdown? What's the command for that?

git clone https://github.com/robinrodricks/FluentStorage.wiki.git

[gumbarros]

Im in a hurry and cannot create a CI file, but it looks like this https://github.com/ncalc/ncalc/blob/master/.github/workflows/pages.yml

the same repo of the lib is the same repo of the GH pages

[robinrodricks]

Yes I understand with github actions you can automate the building of HTML, but I would prefer it in a separate repo so that it can serve on the root subdomain fluentstorage.github.io rather than fluentstorage.github.io/docs/

As per my knowledge, you need to create a pages repo for this.

[gumbarros]

for this you need to create a new repo and store the markdown files there, the public api I think can be generated by at the DocFX .csproj referencing the NuGet and pointing to the generated dlls