[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: dotnet/docfx#684 (comment)

[miroiu]

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

[nishant05gaurav]

Hey, there I want to fix this issue:
Steps are:

1. Install DocFX in your build pipeline:

dotnet tool install -g docfx

2. Create docfx.json file:

{
  "metadata": [
    {
      "src": [
        {
          "files": ["**/*.csproj"],
          "exclude": ["**/bin/**", "**/obj/**"]
        }
      ],
      "dest": "obj/api",
      "filter": "filterConfig.yml"
    }
  ],
  "build": {
    "content": [
      {
        "files": ["obj/api/**/*.yml", "toc.yml"]
      }
    ],
    "dest": "docs",
    "output": "markdown",
    "template": ["default"]
  }
}

3. Configure filterConfig.yml:

apiRules:
  exclude:
    - type: Exclude
      uidRegex: ^((?!Nodify).)*$

4. Link WPF Classes in the .liquid templates: Modify the templates to ensure that classes like FrameworkElement are linked to the correct external Microsoft documentation:

{% if item.summary %}
<summary>{{ item.summary | link_external }}</summary>
{% endif %}

5. Set up GitHub Actions: Add a GitHub Action YAML file to your workflow for automated generation:

name: Build Documentation

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install DocFX
        run: dotnet tool install -g docfx
      - name: Build Documentation
        run: |
          docfx metadata
          docfx build --serve
      - name: Deploy to Wiki
        run: |
          # Add logic to push the markdown to GitHub Wiki

[ketanpkolte]

Hi @miroiu is this issue resolved?
If not, I would like to take up this issue

[miroiu]

@nishant05gaurav , do you have a fork with a working pipeline? I want to see what the result looks like.

@ketanpkolte , it's not resolved. Feel free to take the issue. I would like to see a working example.

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

With this change, I think the best approach would be to create a PR to master to replace docs/API-Reference.md with the generated file, and we can manually merge it - which is then automatically synced to the wiki.