feat: use docfx generate docs site automatically

[SteveSuv]

what's changed:

• use docfx to generate api docs site automatically
• add deploy to github pages workflow
• fix ;) to :)

preview:

deploy:

I don't have permission do this step, so need repo author to deploy.
or you can split Site dir to a new repo then deploy.

here's some guide to follow:

• https://dotnet.github.io/docfx/index.html#publish-to-github-pages
• https://docs.github.com/en/pages/quickstart

and when you finished deploy to github pages, you can put site url to repo's about.
has a api docs site will attract more fans :)

[SoloByte]

Thank you very much for this :) I always wanted to do this but never found the time ^^

[SoloByte]

Should I set the GitHub Pages Build and Deployment Source to Github Actions or leave it on Deploy from Branch?

[SteveSuv]

use Github Actions then go Actions tab and rerun workflows.
when finished, the docs site url is https://davegreen-games.github.io/ShapeEngine/

[SoloByte]

I can only run it successfully after I have merged the PR.

Just out of curiosity would either be possible:

• Having a seperate branch like shape-engine-docs were all this exists and a workflow that automaticallly keeps the branch synced with main?
• a seperate public repo for the docs?

If yes would there be major disadvantages?

I am just asking because it adds a lot of files to the repository, which is not a problem if this is the best way to do it, but if there is a way to keep them separate, I would prefer it.

[SteveSuv]

yeah, I also suggest split Site dir's contents to a new repo, maybe named ShapeEngineDocs.
it's more clear and maintainable.
the disadvantage is that you have to manually maintain the src path in docfx.json。

"metadata": [
    {
      "src": [
        {
          "src": "../../ShapeEngine", // here it is
          "files": ["**/*.csproj"],
          "exclude": ["**/Examples/**"]
        }
      ],
      "dest": "api"
    }
  ],

but don't worry, it's not a big probleam.
when you wants to update/sync docs, you can put ShapeEngine repo and ShapeEngineDocs repo to a same local path, for example "~/Desktop", and now the src should be "../ShapeEngine/ShapeEngine". In fact, it is to let src point to ShapeEngine's csproj path. then you can exec cd ~/Desktop/ShapeEngineDocs && docfx docfx.json --serve, it will re-generate latest docs automatically.

[SoloByte]

I have created a new ShapeEngineDocs public repository within the DaveGreenGames organization and I invited you as a collaborator.

[SteveSuv]

I have closed this pr.
because the docs repo has been ready.
here is the url: https://davegreen-games.github.io/ShapeEngineDocs
and you can put it to About