Skip to content

[Feature Request] Suppress warnings occurred when using custom filter rules #8841

@filzrev

Description

@filzrev

Is your feature request related to a problem? Please describe.

When using Custom filter rules and run docfx build command.
Following warnings occurred.

Unable to handle following files: filterConfig.yml. Do they miss YamlMime as the first line of file, e.g.: ### YamlMime:ManagedReference?

I knows this warning can be suppressed by explicitly excluding filterConfig.yml from build configs.
But current message seems misleading to fix problem .

Describe the solution you'd like

filter parameter is not passed to SingleDocumentBuilder (Because it is used for docfx metadata command)
So it can't exclude by file path.

I thought, following changes are required to suppress warnings.

  1. Add new FilterConfig YAML mime type definition.

    public const string YamlMimePrefix = nameof(YamlMime) + ":";
    public const string ManagedReference = YamlMimePrefix + nameof(ManagedReference);
    public const string TableOfContent = YamlMimePrefix + nameof(TableOfContent);
    public const string XRefMap = YamlMimePrefix + nameof(XRefMap);

  2. Suppress warning occurred (by reading YAML mime)

    var notToHandleItems = files
    .Where(s => s.Key == null)
    .SelectMany(s => s)
    .Where(s => s.Type != DocumentType.Overwrite &&
    !s.File.EndsWith(".yaml.md", StringComparison.OrdinalIgnoreCase) &&
    !s.File.EndsWith(".yml.md", StringComparison.OrdinalIgnoreCase))
    .ToList();
    if (notToHandleItems.Count > 0)
    {
    Logger.LogWarning(
    $"Unable to handle following files: {notToHandleItems.Select(s => s.File).ToDelimitedString()}. Do they miss `YamlMime` as the first line of file, e.g.: `### YamlMime:ManagedReference`?",
    code: WarningCodes.Build.UnknownContentType);
    }

  3. Add YAML mime to filterConfig.yml file header.
    ### YamlMime:FilterConfig

Metadata

Metadata

Assignees

No one assigned

    Labels

    dotnetGenerate .NET API reference docsdotnet: api-filterFilter APIs for .NET API reference docs

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions