dotnet / docfx

Static site generator for .NET API documentation.
https://dotnet.github.io/docfx/
MIT License
4.06k stars 862 forks source link

Only some attributes are pulled into the auto-generated api .yaml files #10173

Open cjsha opened 1 month ago

cjsha commented 1 month ago

Describe the bug For example:

The relevant files for this example are: OpenEphys.Onix1.ConfigureHeartbeart.yml (generated locally by docfx metadata command) and ConfigureHeartbeart.cs

To Reproduce Steps to reproduce the behavior:

  1. The simplest way might be to fork this repo and build it to see for yourself. But I can try to distill the issue further if y'all want/need

Expected behavior All attributes are pullled into the .yml file after running the metadata command

Context (please complete the following information):

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "src/**.csproj"
          ]
        }
      ],
      "dest": "api",
      "filter": "filter.yml",
      "enumSortOrder": "declaringOrder"
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "api/**.yml",
          "articles/**.md",
          "articles/**/toc.yml",
          "tutorials/**.md",
          "tutorials/**/toc.yml",
          "toc.yml",
          "*.md"
        ],
        "exclude": "tutorials/devices/**"
      }
    ],
    "resource": [
      {
        "files": [
          "logo.svg",
          "favicon.png",
          "images/**",
          "workflows/**"
        ]
      }
    ],
    "output": "_site",
    "overwrite": [
      {
        "files": [
        ],
        "exclude": [
          "obj/**",
          "_site/**"
        ]
      }
    ],
    "template": [
      "default",
      "modern",
      "template",
      "docfx-tools/template"
    ],
    "globalMetadata": {
      "_enableNewTab": true,
      "_enableSearch": true,
      "pdf": false,
      "_appFooter": "&copy; 2024 Open Ephys and Contributors. Made with <a href=\"https://dotnet.github.io/docfx\">docfx</a>",
      "_appFaviconPath": "favicon.png"
    },
    "markdownEngineName": "markdig",
    "markdownEngineProperties": {
      "markdigExtensions": [
        "attributes",
        "customcontainers"
      ]
    },
    "xref": [
      "https://bonsai-rx.org/docs/xrefmap.yml",
      "https://horizongir.github.io/opencv.net/xrefmap.yml",
      "https://horizongir.github.io/reactive/xrefmap.yml"
    ]
  }
}
.NET SDK:
 Version:           8.0.301
 Commit:            1a0e9c0300
 Workload version:  8.0.300-manifests.68207d42
 MSBuild version:   17.10.4+10fbfbf2e

Runtime Environment:
 OS Name:     Windows
 OS Version:  10.0.22631
 OS Platform: Windows
 RID:         win-x64
 Base Path:   C:\Program Files\dotnet\sdk\8.0.301\

.NET workloads installed:
 [maui-windows]
   Installation Source: VS 17.8.34511.84
   Manifest Version:    8.0.3/8.0.100
   Manifest Path:       C:\Program Files\dotnet\sdk-manifests\8.0.100\microsoft.net.sdk.maui\8.0.3\WorkloadManifest.json
   Install Type:              Msi

 [maccatalyst]
   Installation Source: VS 17.8.34511.84
   Manifest Version:    17.2.8004/8.0.100
   Manifest Path:       C:\Program Files\dotnet\sdk-manifests\8.0.100\microsoft.net.sdk.maccatalyst\17.2.8004\WorkloadManifest.json
   Install Type:              Msi

 [ios]
   Installation Source: VS 17.8.34511.84
   Manifest Version:    17.2.8004/8.0.100
   Manifest Path:       C:\Program Files\dotnet\sdk-manifests\8.0.100\microsoft.net.sdk.ios\17.2.8004\WorkloadManifest.json
   Install Type:              Msi

 [android]
   Installation Source: VS 17.8.34511.84
   Manifest Version:    34.0.43/8.0.100
   Manifest Path:       C:\Program Files\dotnet\sdk-manifests\8.0.100\microsoft.net.sdk.android\34.0.43\WorkloadManifest.json
   Install Type:              Msi

Host:
  Version:      8.0.6
  Architecture: x64
  Commit:       3b8b000a0e

.NET SDKs installed:
  8.0.101 [C:\Program Files\dotnet\sdk]
  8.0.301 [C:\Program Files\dotnet\sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 8.0.1 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 8.0.6 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 6.0.32 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 8.0.1 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 8.0.6 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.WindowsDesktop.App 8.0.1 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
  Microsoft.WindowsDesktop.App 8.0.6 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]

Other architectures found:
  x86   [C:\Program Files (x86)\dotnet]
    registered at [HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x86\InstallLocation]

Environment variables:
  Not set

global.json file:
  Not found

Learn more:
  https://aka.ms/dotnet/info

Download .NET:
  https://aka.ms/dotnet/download

Additional context I'm not sure if we're doing something wrong or if this is a docfx bug. Please let me know if I can help. or provide anymore information

cjsha commented 1 day ago

Hi, I'm wondering if I can provide additional information or be of help for this issue. I think it's similar or a duplicate of #9234. Thanks

filzrev commented 1 day ago

[Category(ConfigurationCategory)] & [Description()] are not pulled into syntax.content

These attributes are defined as System.ComponentModel namespace.

So is seems these attributes are excluded by defaultfilterconfig.yml's setting. https://github.com/dotnet/docfx/blob/5683814d296562ef782f703061d01f69bd7899df/src/Docfx.Dotnet/Resources/defaultfilterconfig.yml#L41-L43

How would it work if explicitly including these attributes at custom filter config file settings (filter.yml)

cjsha commented 18 hours ago

Yes! This helped. For anyone who runs into a similar problem, I added these lines to filter.yml

attributeRules:
- include: # this is necessary to pull our custom attributes into .yml metadata without disabling the docfx default filter
    uidRegex: ^System\.ComponentModel\.(CategoryAttribute|DescriptionAttribute)$
    type: Type 

Thanks so much.