Fixes #59. Automatically generate API docs via github action (#65)

* Create dotnet.yml

Upgrading CI/CD to GithubActions

* .NET 6

* Updating workflows

* github package

* tweaking yaml

* Fixed path?

* removed path

* added path back

* ugh

* added gitver

* tweaking ver

* new giver stuff for 18.3

* new publish workflow

* added nuget.org publishing

* renamed master to main

* Cleaned up old build files

* Disable publishing to GitHub Packages

* Disable publishing to GitHub Packages

* Revert to v 0.17

* reverted readme

* Moved to Gui-cs Org

* Creating develop branch & setting up gitflow model

* Auto gen API docs

* Nuke old docs

* Update build script for gitflow

.github/workflows/api-docs.yml

@@ -0,0 +1,42 @@
+name: Build and publish API docs
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  generate-docs:
+    runs-on: windows-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Setup .NET Core
+      uses: actions/setup-dotnet@v1
+      with:
+        dotnet-version: 6.0.100
+
+    - name: Setup DocFX
+      uses: crazy-max/ghaction-chocolatey@v1
+      with:
+        args: install docfx    
+
+    - name: Install dependencies
+      run: dotnet restore        
+
+    - name: DocFX Build
+      working-directory: docfx
+      # https://stackoverflow.com/questions/56726429/how-to-run-multiple-commands-in-one-github-actions-docker
+      run: |
+        rm ../docs -Recurse -Force
+        docfx docfx.json
+      continue-on-error: false      
+
+    - name: Publish
+      if: github.event_name == 'push'
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs
+        force_orphan: true

.github/workflows/build.yml

@@ -1,10 +1,10 @@
-name: Build NStack
+name: Build & Test NStack
 
 on:
   push:
-    branches: [ main ]
+    branches: [ main, develop ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, develop ]
 
 jobs:
   build:

.gitignore

@@ -39,4 +39,13 @@ Thumbs.db
 # dotCover
 *.dotCover
 
-.vs/*
+.vs/*
+
+# API Docs
+docfx/api
+
+# Never push ./docs folder - the gh-pages branch is now used to publish to GH Pages
+docs/
+
+#git merge files
+*.orig

README.md

@@ -6,7 +6,7 @@
 [![License](https://img.shields.io/github/license/migueldeicaza/NStack.svg)](LICENSE)
 ![Bugs](https://img.shields.io/github/issues/migueldeicaza/NStack)
 
-NOTE: NStack has moved to the guo-cs org: https://github.com/orgs/gui-cs/Currently, this library contains a port of the Go string, and Go rune support as well as other Unicode helper methods.
+NOTE: NStack has moved to the gui-cs org: https://github.com/orgs/gui-cs/Currently, this library contains a port of the Go string, and Go rune support as well as other Unicode helper methods.
 
 Currently, this library contains a port of the Go string, and Go rune support as well as other Unicode helper methods.
 

docfx/README.md

@@ -1,12 +1,14 @@
 This folder generates the API docs for NStack. 
 
-The API documentation is generated using the [DocFX tool](https://github.com/dotnet/docfx). The output of docfx gets put into the `./docs` folder which is then checked in. The `./docs` folder is then picked up by Github Pages and published to Miguel's Github Pages (https://migueldeicaza.github.io/NStack/).
+The API documentation is generated via a GitHub Action (`.github/workflows/api-docs.yml`) using [DocFX](https://github.com/dotnet/docfx). The Action publishes the docs to the `gh-pages` branch, which gets published to https://gui-cs.github.io/NStack/.
 
-## To Generate the Docs
+## To Generate the Docs Locally
 
 0. Install DotFX https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html
 1. Change to the `./docfx` folder and run `./build.ps1`
 2. Browse to http://localhost:8080 and verify everything looks good.
 3. Hit ctrl-c to stop the script.
 
 If `docfx` fails with a `Stackoverflow` error. Just run it again. And again. Sometimes it takes a few times. If that doesn't work, create a fresh clone or delete the `docfx/api`, `docfx/obj`, and `docs/` folders and run the steps above again.
+
+Note the `./docfx/build.ps1` script will create a `./docs` folder. This folder is ignored by `.gitignore`.

docfx/build.ps1

@@ -5,5 +5,8 @@ dotnet build --configuration Release ../NStack.sln
 
 rm ../docs -Recurse -Force
 
+
+$env:DOCFX_SOURCE_BRANCH_NAME="main"
+
 docfx --metadata
-docfx --serve
+docfx --serve --force

docfx/docfx.json

@@ -15,7 +15,9 @@
         }
       ],
       "dest": "api/NStack",
-      "shouldSkipMarkup": true
+      "shouldSkipMarkup": true,
+      "properties": {
+        "TargetFramework": "net6.0"
     }
   ],
   "build": {
@@ -65,14 +67,17 @@
     "globalMetadata": {
       "_enableSearch": "true",
       "_appLogoPath": "images/logo48.png",
-      "_disableContribution": true
+      "_disableContribution": false,
+      "_gitContribute": {
+        "repo": "https://github.com/gui-cs/NStack",
+        "branch": "develop",
+        "apiSpecFolder": "docfx/overrides"
+      },
+      "_gitUrlPattern": "github"
     },
     "globalMetadataFiles": [],
     "fileMetadataFiles": [],
-    "template": [
-      "default"
-    ],
-    "postProcessors": [ "ExtractSearchIndex" ],
+    "postProcessors": ["ExtractSearchIndex"],
     "noLangKeyword": false,
     "keepFileLink": false
   }