[Docs] Generate API Reference on build action

[miroiu]

Describe the issue Find a way to generate API Reference from XML comments in the build pipeline (GitHub action) and upload it to the wiki. Please make sure that documentation is generated only for types inside Nodify.dll and that links to WPF classes are pointing to the Microsoft documentation (e.g. references to FrameworkElement will point to this https://learn.microsoft.com/en-us/dotnet/api/system.windows.frameworkelement?view=windowsdesktop-6.0)

Additional context The API Reference was previously generated manually with a custom tool and uploaded to the website but that tool had multiple issues and it could not be used in a pipeline.

[MRfantastic3DGamer]

Hi, I love blender and all the nodes based programs. I would love to help with this.

I created a new workflow for now as followes

name: Generate API Documentation

on:
  push:
    branches:
      - main
      - auto-docs

jobs:
  build-docs:
    runs-on: windows-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v4

    - name: Setup .NET Core 8.x
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: "8.x"

    - name: Setup DocFx
      uses: clFaster/docfx-setup-action@v1

    - name: Build Documentation
      uses: clFaster/docfx-build-action@v1
      with:
        docfx-file-path: "docfx.json"
        docfx-output-path: "Docs"

    - name: Upload Docs artifact
      uses: actions/upload-artifact@v3
      with:
        name: Docs
        path: Docs

  sync-wiki:
    runs-on: ubuntu-latest
    needs: build-docs

    steps:

    - name: Download Docs artifact
      uses: actions/download-artifact@v3
      with:
        name: Docs
        path: Docs
    - uses: spenserblack/actions-wiki@v0.3.0
      with:
        path: Docs

    - name: log all Docs
      run: tree

and it creates the correct documentation, but the thing is that it is creating that in html formatt and not in markdown. these are the created documents.

.
└── Docs
    ├── CHANGELOG.html
    ├── CODE_OF_CONDUCT.html
    ├── CONTRIBUTING.html
    ├── PULL_REQUEST_TEMPLATE.html
    ├── README.html
    ├── api
    │   ├── Nodify.AllGestures.html
    │   ├── Nodify.AnyGesture.html
    │   ├── Nodify.ArrowHeadEnds.html
    │   ├── Nodify.ArrowHeadShape.html
    │   ├── Nodify.BaseConnection.html
    │   ├── Nodify.BoxValue.html
    │   ├── Nodify.CircuitConnection.html
    │   ├── Nodify.Connection.html
    │   ├── Nodify.ConnectionDirection.html
    │   ├── Nodify.ConnectionEventArgs.html
    │   ├── Nodify.ConnectionEventHandler.html
    │   ├── Nodify.ConnectionOffsetMode.html
    │   ├── Nodify.Connector.html
    │   ├── Nodify.ConnectorEventArgs.html
    │   ├── Nodify.ConnectorEventHandler.html
    │   ├── Nodify.ContainerDefaultState.html
    │   ├── Nodify.ContainerDraggingState.html
    │   ├── Nodify.ContainerState.html
    │   ├── Nodify.DecoratorContainer.html
    │   ├── Nodify.EditorCommands.Alignment.html
    │   ├── Nodify.EditorCommands.html
    │   ├── Nodify.EditorDefaultState.html
    │   ├── Nodify.EditorGestures.ConnectionGestures.html
    │   ├── Nodify.EditorGestures.ConnectorGestures.html
    │   ├── Nodify.EditorGestures.GroupingNodeGestures.html
    │   ├── Nodify.EditorGestures.ItemContainerGestures.html
    │   ├── Nodify.EditorGestures.NodifyEditorGestures.html
    │   ├── Nodify.EditorGestures.SelectionGestures.html
    │   ├── Nodify.EditorGestures.html
    │   ├── Nodify.EditorPanningState.html
    │   ├── Nodify.EditorSelectingState.html
    │   ├── Nodify.EditorState.html
    │   ├── Nodify.GroupingMovementMode.html
    │   ├── Nodify.GroupingNode.html
    │   ├── Nodify.INodifyCanvasItem.html
    │   ├── Nodify.InputGestureRef.html
    │   ├── Nodify.ItemContainer.html
    │   ├── Nodify.KnotNode.html
    │   ├── Nodify.LineConnection.html
    │   ├── Nodify.MultiGesture.Match.html
    │   ├── Nodify.MultiGesture.html
    │   ├── Nodify.Node.html
    │   ├── Nodify.NodeInput.html
    │   ├── Nodify.NodeOutput.html
    │   ├── Nodify.NodifyCanvas.html
    │   ├── Nodify.NodifyEditor.html
    │   ├── Nodify.PendingConnection.html
    │   ├── Nodify.PendingConnectionEventArgs.html
    │   ├── Nodify.PendingConnectionEventHandler.html
    │   ├── Nodify.PreviewLocationChanged.html
    │   ├── Nodify.ResizeEventArgs.html
    │   ├── Nodify.ResizeEventHandler.html
    │   ├── Nodify.SelectionHelper.SelectionType.html
    │   ├── Nodify.SelectionHelper.html
    │   ├── Nodify.StateNode.html
    │   ├── Nodify.html
    │   ├── toc.html
    │   ├── toc.json
    │   └── toc.pdf
    ├── favicon.ico
    ├── index.json
    ├── logo.svg
    ├── manifest.json
    ├── search-stopwords.json
    ├── styles
    │   ├── docfx.css
    │   ├── docfx.js
    │   ├── docfx.vendor.min.css
    │   ├── docfx.vendor.min.css.map
    │   ├── docfx.vendor.min.js
    │   ├── docfx.vendor.min.js.map
    │   ├── glyphicons-halflings-regular-ACNUA6UY.ttf
    │   ├── glyphicons-halflings-regular-JOUF32XT.woff
    │   ├── glyphicons-halflings-regular-PIHUWCJO.eot
    │   ├── glyphicons-halflings-regular-QXYEM3FU.svg
    │   ├── glyphicons-halflings-regular-W4DYDFZM.woff2
    │   ├── main.css
    │   ├── main.js
    │   ├── search-worker.min.js
    │   └── search-worker.min.js.map
    ├── toc.html
    ├── toc.json
    └── xrefmap.yml

if anyone knows a fix for this please let me know

[miroiu]

Hi! Did you try following the guide? https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet

[MRfantastic3DGamer]

Yes, I followed that guide but it was no good. Even after specifying clearly that I need markdown by "experimental": { "generateMarkdown": true } and setting markdown engine by "markdownEngineName": "markdig", "markdownEngineProperties": { "markdigExtensions": [ "Abbreviations", "Footnotes" ] } it still doesn't work

[miroiu]

This may be helpful: https://github.com/dotnet/docfx/issues/684#issuecomment-1741710547

[miroiu]

FYI documentation is now stored in a docs folder that's synchronized to the wiki on push to master (related: #113)