diff --git a/docs/reference/docfx-json-reference.md b/docs/reference/docfx-json-reference.md index 401f1c2d5fa..4b092b4a4a2 100644 --- a/docs/reference/docfx-json-reference.md +++ b/docs/reference/docfx-json-reference.md @@ -339,16 +339,27 @@ Do not run `dotnet restore` before building the projects. ### `namespaceLayout` -Defines how namespaces in TOC are organized. When set to *flattened*, renders namespaces as a single flat list. When set to *nested*, renders namespaces in a nested tree form. The default is *flattened*. +Defines how namespaces in TOC are organized: +- `flattened` (default): Renders namespaces as a single flat list. +- `nested`: Renders namespaces in a nested tree form. ### `memberLayout` -Defines how member pages are organized. When set to *samePage*, places members in the same page as their containing type. When set to *separatePages*, places members in separate pages. The default is *samePage*. +Defines how member pages are organized: +- `samePage` (default): Places members in the same page as their containing type. +- `separatePages`: Places members in separate pages. ### `allowCompilationErrors` When enabled, continues documentation generation in case of compilation errors. +### `EnumSortOrder` + +Defines how enum members are sorted: + +- `alphabetic` (default): Sort enum members in alphabetic order. +- `declaringOrder`: Sort enum members in the order as they are declared in the source code. + ## `pdf` Configuration options that are applied for `docfx pdf` command: diff --git a/samples/seed/docfx.json b/samples/seed/docfx.json index c09d194183b..f103937b4c5 100644 --- a/samples/seed/docfx.json +++ b/samples/seed/docfx.json @@ -17,6 +17,7 @@ } ], "namespaceLayout": "nested", + "enumSortOrder": "declaringOrder", "dest": "obj/api" } ], diff --git a/src/Docfx.Dotnet/DotnetApiCatalog.cs b/src/Docfx.Dotnet/DotnetApiCatalog.cs index 0dc13a574dc..03814d4750a 100644 --- a/src/Docfx.Dotnet/DotnetApiCatalog.cs +++ b/src/Docfx.Dotnet/DotnetApiCatalog.cs @@ -125,6 +125,7 @@ private static ExtractMetadataConfig ConvertConfig(MetadataJsonItemConfig config NoRestore = configModel?.NoRestore ?? false, NamespaceLayout = configModel?.NamespaceLayout ?? default, MemberLayout = configModel?.MemberLayout ?? default, + EnumSortOrder = configModel?.EnumSortOrder ?? default, AllowCompilationErrors = configModel?.AllowCompilationErrors ?? false, Files = expandedFiles.Items.SelectMany(s => s.Files).ToList(), References = expandedReferences?.Items.SelectMany(s => s.Files).ToList(), diff --git a/src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataConfig.cs b/src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataConfig.cs index befe01cdaff..5a04e5ea4d4 100644 --- a/src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataConfig.cs +++ b/src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataConfig.cs @@ -29,6 +29,8 @@ internal class ExtractMetadataConfig public MemberLayout MemberLayout { get; init; } + public EnumSortOrder EnumSortOrder { get; init; } + public Dictionary MSBuildProperties { get; init; } public bool AllowCompilationErrors { get; init; } diff --git a/src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataWorker.cs b/src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataWorker.cs index 0d9631c5c16..368bebcfe1c 100644 --- a/src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataWorker.cs +++ b/src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataWorker.cs @@ -232,7 +232,7 @@ private void ResolveAndExportYamlMetadata( var fileName = memberModel.Name.Replace('`', '-'); var outputFileName = GetUniqueFileNameWithSuffix(fileName + Constants.YamlExtension, outputFileNames); string itemFilePath = Path.Combine(_config.OutputFolder, outputFileName); - var memberViewModel = memberModel.ToPageViewModel(); + var memberViewModel = memberModel.ToPageViewModel(_config); memberViewModel.ShouldSkipMarkup = _config.ShouldSkipMarkup; memberViewModel.MemberLayout = _config.MemberLayout; YamlUtility.Serialize(itemFilePath, memberViewModel, YamlMime.ManagedReference); diff --git a/src/Docfx.Dotnet/MetadataJsonConfig.cs b/src/Docfx.Dotnet/MetadataJsonConfig.cs index 71d7c421507..4a5f50bc639 100644 --- a/src/Docfx.Dotnet/MetadataJsonConfig.cs +++ b/src/Docfx.Dotnet/MetadataJsonConfig.cs @@ -31,6 +31,22 @@ internal enum NamespaceLayout Nested, } +/// +/// Specifies the sort order for enums. +/// +internal enum EnumSortOrder +{ + /// + /// Sorts enums in alphabetic order. + /// + Alphabetic, + + /// + /// Sorts enums in the order they are declared. + /// + DeclaringOrder +} + /// /// MetadataJsonItemConfig. /// @@ -67,7 +83,6 @@ internal class MetadataJsonItemConfig [JsonProperty("filter")] public string FilterConfigFile { get; set; } - /// /// Include private or internal APIs. /// The default is false. @@ -114,23 +129,28 @@ internal class MetadataJsonItemConfig public bool NoRestore { get; set; } /// - /// Defines how namespaces in TOC are organized. - /// When set to flattened, renders namespaces as a single flat list. - /// When set to nested, renders namespaces in a nested tree form. - /// The default is flattened. + /// Defines how namespaces in TOC are organized: + /// - `flattened` (default): Renders namespaces as a single flat list. + /// - `nested`: Renders namespaces in a nested tree form. /// [JsonProperty("namespaceLayout")] public NamespaceLayout NamespaceLayout { get; set; } /// - /// Defines how member pages are organized. - /// When set to samePage, places members in the same page as their containing type. - /// When set to separatePages, places members in separate pages. - /// The default is samePage. + /// Defines how member pages are organized: + /// - `samePage` (default): Places members in the same page as their containing type. + /// - `separatePages`: Places members in separate pages. /// [JsonProperty("memberLayout")] public MemberLayout MemberLayout { get; set; } + /// + /// Defines how member pages are organized: + /// - `samePage` (default): Places members in the same page as their containing type. + /// - `separatePages`: Places members in separate pages. + /// + public EnumSortOrder EnumSortOrder { get; init; } + /// /// When enabled, continues documentation generation in case of compilation errors. /// diff --git a/src/Docfx.Dotnet/YamlViewModelExtensions.cs b/src/Docfx.Dotnet/YamlViewModelExtensions.cs index af5e1980289..4c24a2e95dc 100644 --- a/src/Docfx.Dotnet/YamlViewModelExtensions.cs +++ b/src/Docfx.Dotnet/YamlViewModelExtensions.cs @@ -150,17 +150,17 @@ public static TocItemViewModel ToTocItemViewModel(this MetadataItem item, string return result; } - public static PageViewModel ToPageViewModel(this MetadataItem model) + public static PageViewModel ToPageViewModel(this MetadataItem model, ExtractMetadataConfig config) { if (model == null) { return null; } var result = new PageViewModel(); - result.Items.Add(model.ToItemViewModel()); + result.Items.Add(model.ToItemViewModel(config)); if (model.Type.AllowMultipleItems()) { - AddChildren(model, result); + AddChildren(model, result, config); } foreach (var item in model.References) { @@ -229,13 +229,17 @@ private static ReferenceViewModel ToReferenceViewModel(KeyValuePair x.Name).ToList() + : model.Items?.Select(x => x.Name).OrderBy(s => s, StringComparer.Ordinal).ToList(); + var result = new ItemViewModel { Uid = model.Name, @@ -243,7 +247,7 @@ public static ItemViewModel ToItemViewModel(this MetadataItem model) IsExplicitInterfaceImplementation = model.IsExplicitInterfaceImplementation, IsExtensionMethod = model.IsExtensionMethod, Parent = model.Parent?.Name, - Children = model.Items?.Select(x => x.Name).OrderBy(s => s, StringComparer.Ordinal).ToList(), + Children = children, Type = model.Type, Source = model.Source, Documentation = model.Documentation, @@ -372,14 +376,14 @@ public static TValue GetLanguageProperty(this SortedList 0) { foreach (var item in model.Items) { - result.Items.Add(item.ToItemViewModel()); - AddChildren(item, result); + result.Items.Add(item.ToItemViewModel(config)); + AddChildren(item, result, config); } } }