more docfx stuff

.github/workflows/api-docs.yml

@@ -26,14 +26,15 @@ jobs:
         dotnet-version: 7.0
         dotnet-quality: 'ga'
     
-    - name: Setup DocFX
-      uses: crazy-max/ghaction-chocolatey@v2
-      with:
-        args: install docfx    
+    # - name: Setup DocFX
+    #   uses: crazy-max/ghaction-chocolatey@v2
+    #   with:
+    #     args: install docfx    
 
     - name: DocFX Build
       working-directory: docfx
       run: |
+        dotnet tool install -g docfx
         rm ../docs -Recurse -Force -ErrorAction SilentlyContinue
         rm ../api -Recurse -Force -ErrorAction SilentlyContinue
         $env:DOCFX_SOURCE_BRANCH_NAME="${{ github.ref_name }}"

Terminal.sln

@@ -15,6 +15,7 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{E143FB1F-0B88-48CB-9086-72CDCECFCD22}"
 	ProjectSection(SolutionItems) = preProject
 		.gitignore = .gitignore
+		.github\workflows\api-docs.yml = .github\workflows\api-docs.yml
 		.github\CODEOWNERS = .github\CODEOWNERS
 		CODE_OF_CONDUCT.md = CODE_OF_CONDUCT.md
 		CONTRIBUTING.md = CONTRIBUTING.md

docfx/build.ps1

@@ -5,6 +5,8 @@ $prevPwd = $PWD; Set-Location -ErrorAction Stop -LiteralPath $PSScriptRoot
 try {
     $PWD  # output the current location 
 
+    dotnet tool update -g docfx
+
     dotnet build --configuration Release ../Terminal.sln
 
     rm ../docs -Recurse -Force -ErrorAction SilentlyContinue

docfx/docfx.json

@@ -91,7 +91,7 @@
     "globalMetadata": {
       "_appTitle": "Terminal.Gui v2",
       "_appName": "Terminal.Gui v2",
-      "_appFaviconPath": "images/favicon.png",
+      "_appFaviconPath": "images/icon48.png",
       "_appLogoPath": "images/logo.png",
       "_appFooter": "<strong>Terminal.Gui - Part of the gui-cs Organization</strong>",
       "_enableSearch": true,
@@ -108,6 +108,7 @@
       },
       "_gitUrlPattern": "github"
     },
+    "markdownEngineName": "markdig",
     "globalMetadataFiles": [],
     "fileMetadataFiles": [],
     "postProcessors": ["ExtractSearchIndex"],

docfx/plugins/memberpage-extras/ManagedReference.extension.js

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
+var common = require('./ManagedReference.common.js');
+
+exports.preTransform = function (model) {
+    transform(model);
+
+    function transform(item) {        
+        if (item.children) item.children.forEach(function(i) {
+            transform(i);
+        });
+    }
+
+    return model;
+}
+
+exports.postTransform = function (model) {
+    var type = model.type.toLowerCase();
+    var category = common.getCategory(type);
+    if (category == 'class') {
+        var typePropertyName = common.getTypePropertyName(type);
+        if (typePropertyName) {
+            model[typePropertyName] = true;
+        }
+        if (model.children && model.children.length > 0) {
+            model.isCollection = true;
+            common.groupChildren(model, 'class');
+        } else {
+            model.isItem = true;
+        }
+    }
+
+    return model;
+}

docfx/plugins/memberpage-extras/toc.html.js

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
+exports.transform = function (model) {
+    var groupNames = {
+        "constructor": { key: "constructorsInSubtitle" },
+        "field":       { key: "fieldsInSubtitle" },
+        "property":    { key: "propertiesInSubtitle" },
+        "method":      { key: "methodsInSubtitle" },
+        "event":       { key: "eventsInSubtitle" },
+        "operator":    { key: "operatorsInSubtitle" },
+        "eii":         { key: "eiisInSubtitle" },
+    };
+
+    groupChildren(model);
+    transformItem(model, 1);
+    return model;
+
+    function groupChildren(item) {
+        if (!item || !item.items || item.items.length == 0) {
+            return;
+        }
+        var grouped = {};
+        var items = [];
+        item.items.forEach(function (element) {
+            groupChildren(element);
+            if (element.type) {
+                var type = element.isEii ? "eii" : element.type.toLowerCase();
+                if (!grouped.hasOwnProperty(type)) {
+                    if (!groupNames.hasOwnProperty(type)) {
+                        groupNames[type] = {
+                            name: element.type
+                        };
+                        console.log(type + " is not predefined type, use its type name as display name.")
+                    }
+                    grouped[type] = [];
+                }
+                grouped[type].push(element);
+            } else {
+                items.push(element);
+            }
+        }, this);
+        
+        // With order defined in groupNames
+        for (var key in groupNames) {
+            if (groupNames.hasOwnProperty(key) && grouped.hasOwnProperty(key)) {
+                items.push({
+                    name: model.__global[groupNames[key].key] || groupNames[key].name,
+                    items: grouped[key]
+                })
+            }
+        }
+
+        item.items = items;
+    }
+
+    function transformItem(item, level) {
+        // set to null in case mustache looks up
+        item.topicHref = item.topicHref || null;
+        item.tocHref = item.tocHref || null;
+        item.name = item.name || null;
+
+        item.level = level;
+
+        // Add word break opportunities before dots
+
+        if (item.name)
+            item.name = item.name.replace(/\./g, "\u200B.");
+
+        if (item.items && item.items.length > 0) {
+            item.leaf = false;
+            var length = item.items.length;
+            for (var i = 0; i < length; i++) {
+                transformItem(item.items[i], level + 1);
+            };
+        } else {
+            item.items = [];
+            item.leaf = true;
+        }
+    }
+}

docfx/plugins/memberpage.2.59.4/ManagedReference.extension.js

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
+var common = require('./ManagedReference.common.js');
+
+exports.postTransform = function (model) {
+    var type = model.type.toLowerCase();
+    var category = common.getCategory(type);
+    if (category == 'class') {
+        var typePropertyName = common.getTypePropertyName(type);
+        if (typePropertyName) {
+            model[typePropertyName] = true;
+        }
+        if (model.children && model.children.length > 0) {
+            model.isCollection = true;
+            common.groupChildren(model, 'class');
+        } else {
+            model.isItem = true;
+        }
+    }
+    return model;
+}

docfx/plugins/memberpage.2.59.4/ManagedReference.overwrite.js

@@ -0,0 +1,10 @@
+// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
+var common = require('./ManagedReference.common.js');
+
+exports.getOptions = function (model) {
+  var ignoreChildrenBookmarks = model._splitReference && model.type && common.getCategory(model.type) === 'ns';
+
+  return {
+    "bookmarks": common.getBookmarks(model, ignoreChildrenBookmarks)
+  };
+}

docfx/plugins/memberpage.2.59.4/partials/class.tmpl.partial

@@ -0,0 +1,59 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+
+{{>partials/class.header}}
+{{#children}}
+{{#overload}}
+<a id="{{id}}" data-uid="{{uid}}"></a>
+{{/overload}}
+<h3 id="{{id}}">{{>partials/classSubtitle}}</h3>
+{{#children.0}}
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.name}}</th>
+      <th>{{__global.description}}</th>
+    </tr>
+  </thead>
+  <tbody>
+  {{/children.0}}
+    {{#children}}
+    <tr>
+      <td id="{{id}}" data-uid="{{uid}}">
+        <xref uid="{{uid}}" altProperty="fullName" displayProperty="name"/>
+      </td>
+      <td class="markdown level1 summary">{{{summary}}}</td>
+    </tr>
+    {{/children}}    
+  {{#children.0}}
+  </tbody>
+</table>
+{{/children.0}}
+{{/children}}
+{{#extensionMethods.0}}
+<h3 id="extensionmethods">{{__global.extensionMethods}}</h3>
+{{/extensionMethods.0}}
+{{#extensionMethods}}
+<div>
+  {{#definition}}
+    <xref uid="{{definition}}" altProperty="fullName" displayProperty="nameWithType"/>
+  {{/definition}}
+  {{^definition}}
+    <xref uid="{{uid}}" altProperty="fullName" displayProperty="nameWithType"/>
+  {{/definition}}
+</div>
+{{/extensionMethods}}
+{{#seealso.0}}
+<h3 id="seealso">{{__global.seealso}}</h3>
+<div class="seealso">
+{{/seealso.0}}
+{{#seealso}}
+  {{#isCref}}
+    <div>{{{type.specName.0.value}}}</div>
+  {{/isCref}}
+  {{^isCref}}
+    <div>{{{url}}}</div>
+  {{/isCref}}
+{{/seealso}}
+{{#seealso.0}}
+</div>
+{{/seealso.0}}

docfx/plugins/memberpage.2.59.4/partials/collection.tmpl.partial

@@ -0,0 +1,234 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+
+<h1 id="{{id}}" data-uid="{{uid}}">{{>partials/title}}</h1>
+<div class="markdown level0 summary">{{{summary}}}</div>
+<div class="markdown level0 conceptual">{{{conceptual}}}</div>
+
+{{#children}}
+{{#children}}
+{{^_disableContribution}}
+{{#docurl}}
+<span class="small pull-right mobile-hide">
+  <span class="divider">|</span>
+  <a href="{{docurl}}">{{__global.improveThisDoc}}</a>
+</span>{{/docurl}}
+{{#sourceurl}}
+<span class="small pull-right mobile-hide">
+  <a href="{{sourceurl}}">{{__global.viewSource}}</a>
+</span>{{/sourceurl}}
+{{/_disableContribution}}
+{{#overload}}
+<a id="{{id}}" data-uid="{{uid}}"></a>
+{{/overload}}
+<h4 id="{{id}}" data-uid="{{uid}}">{{name.0.value}}</h4>
+<div class="markdown level1 summary">{{{summary}}}</div>
+<div class="markdown level1 conceptual">{{{conceptual}}}</div>
+<h5 class="decalaration">{{__global.declaration}}</h5>
+{{#syntax}}
+<div class="codewrapper">
+  <pre><code class="lang-{{_lang}} hljs">{{syntax.content.0.value}}</code></pre>
+</div>
+{{#parameters.0}}
+<h5 class="parameters">{{__global.parameters}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.type}}</th>
+      <th>{{__global.name}}</th>
+      <th>{{__global.description}}</th>
+    </tr>
+  </thead>
+  <tbody>
+{{/parameters.0}}
+{{#parameters}}
+    <tr>
+      <td>{{{type.specName.0.value}}}</td>
+      <td><span class="parametername">{{{id}}}</span></td>
+      <td>{{{description}}}</td>
+    </tr>
+{{/parameters}}
+{{#parameters.0}}
+  </tbody>
+</table>
+{{/parameters.0}}
+{{#return}}
+<h5 class="returns">{{__global.returns}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.type}}</th>
+      <th>{{__global.description}}</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>{{{type.specName.0.value}}}</td>
+      <td>{{{description}}}</td>
+    </tr>
+  </tbody>
+</table>
+{{/return}}
+{{#typeParameters.0}}
+<h5 class="typeParameters">{{__global.typeParameters}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.name}}</th>
+      <th>{{__global.description}}</th>
+    </tr>
+  </thead>
+  <tbody>
+{{/typeParameters.0}}
+{{#typeParameters}}
+    <tr>
+      <td><span class="parametername">{{{id}}}</span></td>
+      <td>{{{description}}}</td>
+    </tr>
+{{/typeParameters}}
+{{#typeParameters.0}}
+  </tbody>
+</table>
+{{/typeParameters.0}}
+{{#fieldValue}}
+<h5 class="fieldValue">{{__global.fieldValue}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.type}}</th>
+      <th>{{__global.description}}</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>{{{type.specName.0.value}}}</td>
+      <td>{{{description}}}</td>
+    </tr>
+  </tbody>
+</table>
+{{/fieldValue}}
+{{#propertyValue}}
+<h5 class="propertyValue">{{__global.propertyValue}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.type}}</th>
+      <th>{{__global.description}}</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>{{{type.specName.0.value}}}</td>
+      <td>{{{description}}}</td>
+    </tr>
+  </tbody>
+</table>
+{{/propertyValue}}
+{{#eventType}}
+<h5 class="eventType">{{__global.eventType}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.type}}</th>
+      <th>{{__global.description}}</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>{{{type.specName.0.value}}}</td>
+      <td>{{{description}}}</td>
+    </tr>
+  </tbody>
+</table>
+{{/eventType}}
+{{/syntax}}
+{{#overridden}}
+<h5 class="overrides">{{__global.overrides}}</h5>
+<div><xref uid="{{uid}}" altProperty="fullName" displayProperty="nameWithType"/></div>
+{{/overridden}}
+{{#implements.0}}
+<h5 class="implements">{{__global.implements}}</h5>
+{{/implements.0}}
+{{#implements}}
+  {{#definition}}
+    <div><xref uid="{{definition}}" altProperty="fullName" displayProperty="nameWithType"/></div>
+  {{/definition}}
+  {{^definition}}
+    <div><xref uid="{{uid}}" altProperty="fullName" displayProperty="nameWithType"/></div>
+  {{/definition}}
+{{/implements}}
+{{#remarks}}
+<h5 id="{{id}}_remarks">{{__global.remarks}}</h5>
+<div class="markdown level1 remarks">{{{remarks}}}</div>
+{{/remarks}}
+{{#example.0}}
+<h5 id="{{id}}_examples">{{__global.examples}}</h5>
+{{/example.0}}
+{{#example}}
+{{{.}}}
+{{/example}}
+{{#exceptions.0}}
+<h5 class="exceptions">{{__global.exceptions}}</h5>
+<table class="table table-bordered table-striped table-condensed">
+  <thead>
+    <tr>
+      <th>{{__global.type}}</th>
+      <th>{{__global.condition}}</th>
+    </tr>
+  </thead>
+  <tbody>
+{{/exceptions.0}}
+{{#exceptions}}
+    <tr>
+      <td>{{{type.specName.0.value}}}</td>
+      <td>{{{description}}}</td>
+    </tr>
+{{/exceptions}}
+{{#exceptions.0}}
+  </tbody>
+</table>
+{{/exceptions.0}}
+{{#seealso.0}}
+<h5 id="{{id}}_seealso">{{__global.seealso}}</h5>
+<div class="seealso">
+{{/seealso.0}}
+{{#seealso}}
+  {{#isCref}}
+    <div>{{{type.specName.0.value}}}</div>
+  {{/isCref}}
+  {{^isCref}}
+    <div>{{{url}}}</div>
+  {{/isCref}}
+{{/seealso}}
+{{#seealso.0}}
+</div>
+{{/seealso.0}}
+{{/children}}
+{{/children}}
+{{#extensionMethods.0}}
+<h3 id="extensionmethods">{{__global.extensionMethods}}</h3>
+{{/extensionMethods.0}}
+{{#extensionMethods}}
+<div>
+  {{#definition}}
+    <xref uid="{{definition}}" altProperty="fullName" displayProperty="nameWithType"/>
+  {{/definition}}
+  {{^definition}}
+    <xref uid="{{uid}}" altProperty="fullName" displayProperty="nameWithType"/>
+  {{/definition}}
+</div>
+{{/extensionMethods}}
+{{#seealso.0}}
+<h3 id="seealso">{{__global.seealso}}</h3>
+<div class="seealso">
+{{/seealso.0}}
+{{#seealso}}
+  {{#isCref}}
+    <div>{{{type.specName.0.value}}}</div>
+  {{/isCref}}
+  {{^isCref}}
+    <div>{{{url}}}</div>
+  {{/isCref}}
+{{/seealso}}
+{{#seealso.0}}
+</div>
+{{/seealso.0}}

docfx/plugins/memberpage.2.59.4/partials/customMREFContent.tmpl.partial

@@ -0,0 +1,7 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+{{#isCollection}}
+{{>partials/collection}}
+{{/isCollection}}
+{{#isItem}}
+{{>partials/item}}
+{{/isItem}}

docfx/plugins/memberpage.2.59.4/partials/item.tmpl.partial

@@ -0,0 +1,3 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+
+{{>partials/class.header}}

docfx/plugins/memberpage.2.59.4/plugins/docfx.plugins.config

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<configuration>
+  <runtime>
+    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
+      <dependentAssembly>
+        <assemblyIdentity name="System.Runtime.CompilerServices.Unsafe" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
+        <bindingRedirect oldVersion="0.0.0.0-5.0.0.0" newVersion="5.0.0.0" />
+      </dependentAssembly>
+      <dependentAssembly>
+        <assemblyIdentity name="System.Collections.Immutable" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
+        <bindingRedirect oldVersion="0.0.0.0-5.0.0.0" newVersion="5.0.0.0" />
+      </dependentAssembly>
+      <dependentAssembly>
+        <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
+        <bindingRedirect oldVersion="0.0.0.0-4.0.1.2" newVersion="4.0.1.2" />
+      </dependentAssembly>
+    </assemblyBinding>
+  </runtime>
+</configuration>

docfx/plugins/memberpage.2.59.4/toc.html.js

@@ -0,0 +1,73 @@
+// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
+exports.transform = function (model) {
+    var groupNames = {
+        "constructor": { key: "constructorsInSubtitle" },
+        "field":       { key: "fieldsInSubtitle" },
+        "property":    { key: "propertiesInSubtitle" },
+        "method":      { key: "methodsInSubtitle" },
+        "event":       { key: "eventsInSubtitle" },
+        "operator":    { key: "operatorsInSubtitle" },
+    };
+
+    groupChildren(model);
+    transformItem(model, 1);
+    return model;
+
+    function groupChildren(item) {
+        if (!item || !item.items || item.items.length == 0) {
+            return;
+        }
+        var grouped = {};
+        var items = [];
+        item.items.forEach(function (element) {
+            groupChildren(element);
+            if (element.type) {
+                var type = element.type.toLowerCase();
+                if (!grouped.hasOwnProperty(type)) {
+                    if (!groupNames.hasOwnProperty(type)) {
+                        groupNames[type] = {
+                            name: element.type
+                        };
+                        console.log(type + " is not predefined type, use its type name as display name.")
+                    }
+                    grouped[type] = [];
+                }
+                grouped[type].push(element);
+            } else {
+                items.push(element);
+            }
+        }, this);
+        
+        // With order defined in groupNames
+        for (var key in groupNames) {
+            if (groupNames.hasOwnProperty(key) && grouped.hasOwnProperty(key)) {
+                items.push({
+                    name: model.__global[groupNames[key].key] || groupNames[key].name,
+                    items: grouped[key]
+                })
+            }
+        }
+
+        item.items = items;
+    }
+
+    function transformItem(item, level) {
+        // set to null in case mustache looks up
+        item.topicHref = item.topicHref || null;
+        item.tocHref = item.tocHref || null;
+        item.name = item.name || null;
+
+        item.level = level;
+
+        if (item.items && item.items.length > 0) {
+            item.leaf = false;
+            var length = item.items.length;
+            for (var i = 0; i < length; i++) {
+                transformItem(item.items[i], level + 1);
+            };
+        } else {
+            item.items = [];
+            item.leaf = true;
+        }
+    }
+}