Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support for automatic generation of device metadata and register tables #4

Merged
merged 12 commits into from
Nov 10, 2023
12 changes: 12 additions & 0 deletions .config/dotnet-tools.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"version": 1,
"isRoot": true,
"tools": {
"docfx": {
"version": "2.73.1",
"commands": [
"docfx"
]
}
}
}
14 changes: 10 additions & 4 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,19 +15,25 @@ jobs:
with:
submodules: recursive

- name: Setup .NET Core SDK
uses: actions/setup-dotnet@v3.2.0
with:
dotnet-version: 7.x

- name: Custom Build Steps
run: .\build.ps1

- name: Setup MSBuild
uses: microsoft/setup-msbuild@v1

- name: Restore NuGet Packages
run: msbuild -t:restore src\harp\Bonsai.Harp.sln

- name: Setup DocFX
uses: crazy-max/ghaction-chocolatey@v1
with:
args: install docfx
run: dotnet tool restore

- name: Build Documentation
run: docfx docfx.json
run: dotnet docfx docfx.json

- name: Checkout gh-pages
uses: actions/checkout@v2
Expand Down
4 changes: 4 additions & 0 deletions apispec/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
###############
# Auto file #
###############
*.md
6 changes: 6 additions & 0 deletions build.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
$files = Get-ChildItem .\src\device.*\device.yml
foreach ($file in $files)
{
Write-Output "Generating schema tables for $file..."
dotnet run --project .\src\harp.schemaprocessor $file .\apispec
}
8 changes: 5 additions & 3 deletions docfx.json
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,8 @@
"files": [
"logo.svg",
"favicon.ico",
"editor/index.html",
"src/device.*/Assets/*.png",
"src/device.*/Assets/*.jpg",
"images/**",
"workflows/**"
]
Expand All @@ -53,7 +54,8 @@
"overwrite": [
{
"files": [
"apidoc/**.md"
"apidoc/**.md",
"apispec/**.md"
],
"exclude": [
"obj/**",
Expand Down Expand Up @@ -88,7 +90,7 @@
"keepFileLink": false,
"cleanupCacheHistory": false,
"disableGitFeatures": false,
"xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ],
"xrefService": [ "https://learn.microsoft.com/api/xref/query?uid={uid}" ],
"xref": [
"https://bonsai-rx.org/docs/xrefmap.yml",
"https://horizongir.github.io/opencv.net/xrefmap.yml",
Expand Down
19 changes: 19 additions & 0 deletions src/harp.schemaprocessor/ExpandoHelper.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
using System.Dynamic;

static class ExpandoHelper
{
public static ExpandoObject FromDictionary(Dictionary<object, object> members, params string[] optionalMembers)
{
var result = new ExpandoObject();
foreach (var kvp in members)
{
result.TryAdd((string)kvp.Key, kvp.Value);
}

foreach (var member in optionalMembers)
{
result.TryAdd(member, null);
}
return result;
}
}
93 changes: 93 additions & 0 deletions src/harp.schemaprocessor/Program.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
using System.Dynamic;
using System.Text;
using YamlDotNet.Core;
using YamlDotNet.Serialization;

var fileName = args[0];
var yaml = File.ReadAllText(fileName);
var deserializer = new Deserializer();
var parser = new MergingParser(new Parser(new StringReader(yaml)));
dynamic deviceModel = deserializer.Deserialize<ExpandoObject>(parser);

var builder = new StringBuilder();
builder.AppendLine($@"---
uid: Harp.{deviceModel.device}.Device
---

<table>
<thead>
<tr><th colspan=""2"">{deviceModel.device}</th></tr>
</thead>
<tbody>
<tr><td>whoAmI</td><td>{deviceModel.whoAmI}</td></tr>
<tr><td>firmwareVersion</td><td>{deviceModel.firmwareVersion}</td></tr>
<tr><td>hardwareTargets</td><td>{deviceModel.hardwareTargets}</td></tr>
</tbody>
</table>

### Registers

| name | address | type | length | access | description | range | interfaceType |
|-|-|-|-|-|-|-|-|");
foreach (var item in deviceModel.registers)
{
if (item.Value.TryGetValue("visibility", out object visibility) &&
(string)visibility == "private")
{
continue;
}

var name = item.Key;
var register = ExpandoHelper.FromDictionary(item.Value,
"length",
"description",
"minValue",
"maxValue",
"defaultValue",
"payloadSpec",
"maskType",
"interfaceType");
var interfaceType = register.maskType
?? register.interfaceType
?? (register.payloadSpec != null ? $"{name}Payload" : null);
var interfaceTypeRef = (string)interfaceType == "EnableFlag"
? "Bonsai.Harp.EnableFlag"
: $"Harp.{deviceModel.device}.{interfaceType}";

var access = register.access;
if (access is List<object> accessList)
{
access = string.Join(", ", accessList);
}

var range = "";
if (register.minValue != null || register.maxValue != null)
{
range = $"[{register.minValue}:{register.maxValue}]";
}
if (register.defaultValue != null) range = $"{register.defaultValue} {range}";

builder.AppendLine(
$"| [{name}](xref:Harp.{deviceModel.device}.{name}) " +
$"| {register.address} " +
$"| {register.type} " +
$"| {register.length} " +
$"| {access} " +
$"| {register.description} " +
$"| {range} " +
(interfaceType != null ? $"| [{interfaceType}](xref:{interfaceTypeRef}) |" : "| |"));
}

var output = builder.ToString();
if (args.Length > 1)
{
File.WriteAllText(Path.Combine(args[1], $"Harp_{deviceModel.device}_Device.md"), output);
File.WriteAllText(Path.Combine(args[1], $"Harp_{deviceModel.device}.md"), $@"---
uid: Harp.{deviceModel.device}
---

[!include[README](~/src/device.{deviceModel.device.ToLowerInvariant()}/README.md)]

[!include[RegisterTables](./Harp_{deviceModel.device}_Device.md)]");
}
else Console.WriteLine(output);
13 changes: 13 additions & 0 deletions src/harp.schemaprocessor/harp.schemaprocessor.csproj
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<Project Sdk="Microsoft.NET.Sdk">

<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net7.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="YamlDotNet" Version="13.7.1" />
</ItemGroup>

</Project>
25 changes: 25 additions & 0 deletions src/harp.schemaprocessor/harp.schemaprocessor.sln
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@

Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio Version 17
VisualStudioVersion = 17.5.002.0
MinimumVisualStudioVersion = 10.0.40219.1
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "harp.schemaprocessor", "harp.schemaprocessor.csproj", "{EAD0FB15-A769-45D5-8FBE-9E1495AE59C6}"
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
Release|Any CPU = Release|Any CPU
EndGlobalSection
GlobalSection(ProjectConfigurationPlatforms) = postSolution
{EAD0FB15-A769-45D5-8FBE-9E1495AE59C6}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{EAD0FB15-A769-45D5-8FBE-9E1495AE59C6}.Debug|Any CPU.Build.0 = Debug|Any CPU
{EAD0FB15-A769-45D5-8FBE-9E1495AE59C6}.Release|Any CPU.ActiveCfg = Release|Any CPU
{EAD0FB15-A769-45D5-8FBE-9E1495AE59C6}.Release|Any CPU.Build.0 = Release|Any CPU
EndGlobalSection
GlobalSection(SolutionProperties) = preSolution
HideSolutionNode = FALSE
EndGlobalSection
GlobalSection(ExtensibilityGlobals) = postSolution
SolutionGuid = {1C2B33A3-49ED-4B82-AF1B-E2F3FB9E4ACF}
EndGlobalSection
EndGlobal
Loading