Consider static web hosted documentation on Github Pages

[dcuccia]

I was able to quickly validate that DocFx can create static website docs like this:

More info here, and here is how to build from GitHub Actions and host on GitHub Pages.

Is this something we could consider? Would be my personal preference for referencing docs, versus downloading a help file locally.

Repro of the steps I took to build and run locally are as follows:

1. Install DocFx as a global tool:

dotnet tool install -g docfx

3. Navigate to the VTS root code directory and initialize with "quiet" mode:

docfx init -q

4. Update the auto-generated docfx.json file with the following "src" subsection:

"src": [
        {
          "files": [
            "Vts/Vts.csproj",
            "Vts.MonteCarlo.CommandLineApplication/Vts.MonteCarlo.CommandLineApplication.csproj",
            "Vts.MonteCarlo.PostProcessor/Vts.MonteCarlo.PostProcessor.csproj"
          ],
          "src": "../src"
        }
      ],

5. Generate the metadata from the targeted Vts libraries:

docfx metadata docfx_project/docfx.json

6. Build the site and run the tool on localhost:8080:

docfx docfx_project\docfx.json --serve

[lmalenfant]

It was my preference to have something accessible on the web also and we did a lot of research of the different documentation generators. The Sandcastle documentation that we used to generate the chm file also has an option to generate HTML or MarkDown pages but the issue is that the number of pages is simply not workable due to the size of our library and the amount of documentation that is generated.

Initially we had web pages hosted on GoDaddy but they took hours to upload using ftp so without our own hosting server, it wasn't feasible.

I created a separate Wiki in my own repository with the MarkDown pages but because there were hundreds of files, the pages failed to load. If you would like to do some testing with DocFx and our library documentation and you are able to find a workable solution, we would love to have web accessible documentation.

[dcuccia]

Seems to be working :) https://dcuccia.github.io/VTS/

I'll set up a PR from my fork, which has only these changes.

[lmalenfant]

This is great, can we change the name from API Documentation to VTS Documentation and can we have the home page be something similar to the documentation page:
https://virtualphotonics.org/documentation

I don't want to duplicate the main project page readme because then it will need to be updated in 2 places, unless we can make the readme be that first page.

Since we are merging this to master, I would like to fix it before we merge.

[dcuccia]

Yes, for sure - we can tailor it however you want. Do you want to make the edits you'd like? Note there are .md files we can customize for the main page and the API splash page.

[dcuccia]

Oh, maybe you can't make changes? I can create a branch and make the PR go to that branch?

[lmalenfant]

Yes that would be great, if you create a branch, we can merge and then I can use that branch to publish pages and make sure everything looks good before having it use master.