From 82764020c26cd7c19230f0960fb6fa39bb4d25a6 Mon Sep 17 00:00:00 2001 From: Andreas Gruenwald Date: Sat, 20 Jun 2020 18:37:24 +0200 Subject: [PATCH] WIP: Add support for templates Move the 'Include Version' and 'Include AutoGenerated Notice' settings into the settings section for the default template. Remove the 'markdown-preset' and 'no-version' command line parameters, because they are specific to the default template. Remove support for the 'MdDocsMarkdownPreset' MSBuild property, because it is specific to the default template. --- docs/commandline/commands/apireference.md | 31 -------- docs/commandline/commands/commandlinehelp.md | 31 -------- mddocs.settings.json | 16 +++- schemas/configuration/schema.json | 73 ++++++++++--------- .../ApiReferenceConfigurationTest.cs | 12 +-- .../Templates/Default/PageTestBase.cs | 4 +- .../ApiReferenceConfiguration.cs | 9 +-- .../Templates/Default/MemberPage.cs | 2 +- .../Templates/Default/NamespacePage.cs | 2 +- .../Default/OverloadableMemberPage.cs | 2 +- .../Templates/Default/SimpleMemberPage.cs | 2 +- .../Templates/Default/TypePage.cs | 4 +- .../CommandLineHelpConfigurationTest.cs | 20 ++--- .../Default/_Documents/CommandPageTest.cs | 4 +- .../MultiCommandApplicationPageTest.cs | 4 +- .../SingleCommandApplicationPageTest.cs | 4 +- .../CommandLineHelpConfiguration.cs | 8 +- .../Default/_Documents/CommandPage.cs | 4 +- .../_Documents/MultiCommandApplicationPage.cs | 4 +- .../SingleCommandApplicationPage.cs | 4 +- .../Configuration/defaultSettings.json | 8 +- .../GenerateApiReferenceDocumentationTest.cs | 20 ----- .../GenerateCommandLineDocumentationTest.cs | 43 +---------- .../build/Grynwald.MdDocs.MSBuild.props | 3 +- .../build/Grynwald.MdDocs.MSBuild.targets | 2 - .../src/GenerateApiReferenceDocumentation.cs | 3 - .../src/GenerateCommandLineDocumentation.cs | 7 -- src/MdDocs.Test/ApiReferenceOptionsTest.cs | 18 ----- src/MdDocs.Test/CommandLineHelpOptionsTest.cs | 18 ----- src/MdDocs.Test/CommandLineTests.cs | 5 -- src/MdDocs/ApiReferenceOptions.cs | 8 -- src/MdDocs/CommandLineHelpOptions.cs | 6 -- src/MdDocs/OptionsBase.cs | 6 -- 33 files changed, 102 insertions(+), 285 deletions(-) diff --git a/docs/commandline/commands/apireference.md b/docs/commandline/commands/apireference.md index fb60e8ea..30de113f 100644 --- a/docs/commandline/commands/apireference.md +++ b/docs/commandline/commands/apireference.md @@ -16,9 +16,7 @@ Generate API reference documentation for a .NET assembly. ``` mddocs apireference [--assembly|-a ] [--configurationFilePath|-c ] - [--markdown-preset ] [--outdir|-o ] - [--no-version] [--verbose|-v] ``` @@ -28,9 +26,7 @@ mddocs apireference [--assembly|-a ] | --------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | [assembly](#assembly-parameter) | [a](#assembly-parameter) | Path of the assembly to generate documentation for. | | [configurationFilePath](#configurationfilepath-parameter) | [c](#configurationfilepath-parameter) | The path of the configuration file to use. If no configuration file is specified, default settings are used. | -| [markdown\-preset](#markdownpreset-parameter) | | Specifies the preset to use for generating Markdown files. | | [outdir](#outdir-parameter) | [o](#outdir-parameter) | Path of the directory to write the documentation to. If the output directory already exists, all files in the output directory will be deleted. | -| [no\-version](#noversion-parameter) | | Do not include the assembly version in the generated documentation. | | [verbose](#verbose-parameter) | [v](#verbose-parameter) | Show more detailed log output. | ### `assembly` Parameter @@ -61,20 +57,6 @@ The path of the configuration file to use. If no configuration file is specified ___ -### `markdown-preset` Parameter - -Specifies the preset to use for generating Markdown files. - -| | | -| ---------------- | ------------------- | -| Name: | markdown\-preset | -| Position: | *Named parameter* | -| Required: | No | -| Accepted values: | `Default`, `MkDocs` | -| Default value: | `Default` | - -___ - ### `outdir` Parameter Path of the directory to write the documentation to. If the output directory already exists, all files in the output directory will be deleted. @@ -89,19 +71,6 @@ Path of the directory to write the documentation to. If the output directory alr ___ -### `no-version` Parameter - -Do not include the assembly version in the generated documentation. - -| | | -| -------------- | ------------------------- | -| Name: | no\-version | -| Position: | *None (Switch Parameter)* | -| Required: | *No (Switch Parameter)* | -| Default value: | `false` | - -___ - ### `verbose` Parameter Show more detailed log output. diff --git a/docs/commandline/commands/commandlinehelp.md b/docs/commandline/commands/commandlinehelp.md index 61c84cc7..d842a84e 100644 --- a/docs/commandline/commands/commandlinehelp.md +++ b/docs/commandline/commands/commandlinehelp.md @@ -16,9 +16,7 @@ Generate command line help for .NET console application implemented using the 'C ``` mddocs commandlinehelp [--assembly|-a ] [--configurationFilePath|-c ] - [--markdown-preset ] [--outdir|-o ] - [--no-version] [--verbose|-v] ``` @@ -28,9 +26,7 @@ mddocs commandlinehelp [--assembly|-a ] | --------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | [assembly](#assembly-parameter) | [a](#assembly-parameter) | Path of the command line application assembly to generate documentation for. | | [configurationFilePath](#configurationfilepath-parameter) | [c](#configurationfilepath-parameter) | The path of the configuration file to use. If no configuration file is specified, default settings are used. | -| [markdown\-preset](#markdownpreset-parameter) | | Specifies the preset to use for generating Markdown files. | | [outdir](#outdir-parameter) | [o](#outdir-parameter) | Path of the directory to write the documentation to. If the output directory already exists, all files in the output directory will be deleted. | -| [no\-version](#noversion-parameter) | | Do not include the application version in the generated documentation. | | [verbose](#verbose-parameter) | [v](#verbose-parameter) | Show more detailed log output. | ### `assembly` Parameter @@ -61,20 +57,6 @@ The path of the configuration file to use. If no configuration file is specified ___ -### `markdown-preset` Parameter - -Specifies the preset to use for generating Markdown files. - -| | | -| ---------------- | ------------------- | -| Name: | markdown\-preset | -| Position: | *Named parameter* | -| Required: | No | -| Accepted values: | `Default`, `MkDocs` | -| Default value: | `Default` | - -___ - ### `outdir` Parameter Path of the directory to write the documentation to. If the output directory already exists, all files in the output directory will be deleted. @@ -89,19 +71,6 @@ Path of the directory to write the documentation to. If the output directory alr ___ -### `no-version` Parameter - -Do not include the application version in the generated documentation. - -| | | -| -------------- | ------------------------- | -| Name: | no\-version | -| Position: | *None (Switch Parameter)* | -| Required: | *No (Switch Parameter)* | -| Default value: | `false` | - -___ - ### `verbose` Parameter Show more detailed log output. diff --git a/mddocs.settings.json b/mddocs.settings.json index 66d0a5e9..add99290 100644 --- a/mddocs.settings.json +++ b/mddocs.settings.json @@ -1,14 +1,22 @@ { + "$schema": "./schemas/configuration/schema.json", "mddocs": { "commandlinehelp": { - "includeVersion" : false, - "outputPath": "./docs/commandline" + "outputPath": "./docs/commandline", + "template": { + "default": { + "includeVersion" : false + } + } }, "apireference" : { - "includeVersion" : false + "template": { + "default": { + "includeVersion" : false + } + } } - } } diff --git a/schemas/configuration/schema.json b/schemas/configuration/schema.json index 62529fe9..16e5eec4 100644 --- a/schemas/configuration/schema.json +++ b/schemas/configuration/schema.json @@ -24,7 +24,8 @@ "$ref": "#/definitions/commandlinehelpConfiguration", "title": "Command Line Help Settings" } - } + }, + "additionalProperties": false }, "commandlinehelpConfiguration": { "type": "object", @@ -47,23 +48,12 @@ "title": "Command Line Help: Output Path", "description": "The directory path to save the generated documentation to." }, - "includeVersion": { - "type": "boolean", - "default": true, - "title": "Command Line Help: Include Version", - "description": "Controls whether the version of the application is included in the generated documentation." - }, - "includeAutoGeneratedNotice": { - "type": "boolean", - "default": true, - "title": "Command Line Help: Include AutoGenerated Notice", - "description": "Controls whether the generated documentation includes a comment that indicates the files were auto-generated." - }, "template": { "$ref": "#/definitions/commandlinehelpTemplateConfiguration", "description": "Specifies settings for templates." } - } + }, + "additionalProperties": false }, "commandlinehelpTemplateConfiguration": { "type": "object", @@ -80,7 +70,8 @@ "title": "Command Line Help: Default Template Settings", "description": "Defines settings for the default template" } - } + }, + "additionalProperties": false }, "commandlinehelpDefaultTemplateConfiguration": { "type": "object", @@ -91,10 +82,23 @@ "Default", "MkDocs" ], - "title": "Command Line Help: Markdown Preset", + "title": "Command Line Help (Default Template): Markdown Preset", "description": "Customizes serialization of Markdown." + }, + "includeVersion": { + "type": "boolean", + "default": true, + "title": "Command Line Help (Default Template): Include Version", + "description": "Controls whether the version of the application is included in the generated documentation." + }, + "includeAutoGeneratedNotice": { + "type": "boolean", + "default": true, + "title": "Command Line Help (Default Template): Include AutoGenerated Notice", + "description": "Controls whether the generated documentation includes a comment that indicates the files were auto-generated." } - } + }, + "additionalProperties": false }, "apireferenceConfiguration": { "type": "object", @@ -117,23 +121,12 @@ "title": "API Reference: Output Path", "description": "The directory path to save the generated documentation to." }, - "includeVersion": { - "type": "boolean", - "default": true, - "title": "API Reference: Include Version", - "description": "Controls whether the version of the assembly is included in the generated documentation." - }, - "includeAutoGeneratedNotice": { - "type": "boolean", - "default": true, - "title": "API Reference: Include AutoGenerated Notice", - "description": "Controls whether the generated documentation includes a comment that indicates the files were auto-generated." - }, "template": { "$ref": "#/definitions/apireferenceTemplateConfiguration", "description": "Specifies settings for templates." } - } + }, + "additionalProperties": false }, "apireferenceTemplateConfiguration": { "type": "object", @@ -150,7 +143,8 @@ "title": "API Reference: Default Template Settings", "description": "Defines settings for the default template" } - } + }, + "additionalProperties": false }, "apireferenceDefaultTemplateConfiguration": { "type": "object", @@ -161,10 +155,23 @@ "Default", "MkDocs" ], - "title": "API Reference: Markdown Preset", + "title": "API Reference (Default Template): Markdown Preset", "description": "Customizes serialization of Markdown." + }, + "includeVersion": { + "type": "boolean", + "default": true, + "title": "API Reference (Default Template): Include Version", + "description": "Controls whether the version of the assembly is included in the generated documentation." + }, + "includeAutoGeneratedNotice": { + "type": "boolean", + "default": true, + "title": "API Reference (Default Template): Include AutoGenerated Notice", + "description": "Controls whether the generated documentation includes a comment that indicates the files were auto-generated." } - } + }, + "additionalProperties": false } } } \ No newline at end of file diff --git a/src/MdDocs.ApiReference.Test/Configuration/ApiReferenceConfigurationTest.cs b/src/MdDocs.ApiReference.Test/Configuration/ApiReferenceConfigurationTest.cs index 8e5c1a10..f3c0645c 100644 --- a/src/MdDocs.ApiReference.Test/Configuration/ApiReferenceConfigurationTest.cs +++ b/src/MdDocs.ApiReference.Test/Configuration/ApiReferenceConfigurationTest.cs @@ -79,11 +79,11 @@ static object[] TestCase(Action assertion) yield return TestCase(config => Assert.NotNull(config)); yield return TestCase(config => Assert.Empty(config.OutputPath)); yield return TestCase(config => Assert.Empty(config.AssemblyPath)); - yield return TestCase(config => Assert.True(config.IncludeAutoGeneratedNotice)); - yield return TestCase(config => Assert.True(config.IncludeVersion)); yield return TestCase(config => Assert.NotNull(config.Template)); yield return TestCase(config => Assert.Equal(ApiReferenceConfiguration.TemplateName.Default, config.Template.Name)); yield return TestCase(config => Assert.NotNull(config.Template.Default)); + yield return TestCase(config => Assert.True(config.Template.Default.IncludeAutoGeneratedNotice)); + yield return TestCase(config => Assert.True(config.Template.Default.IncludeVersion)); yield return TestCase(config => Assert.Equal(MarkdownPreset.Default, config.Template.Default.MarkdownPreset)); } @@ -311,7 +311,7 @@ public void GetConfiguration_does_not_change_the_assembly_path_if_value_is_a_roo public void IncludeAutoGeneratedNotice_can_be_set_in_configuration_file(bool includeAutoGeneratedNotice) { // ARRANGE - PrepareConfiguration("apireference:includeAutoGeneratedNotice", includeAutoGeneratedNotice.ToString()); + PrepareConfiguration("apireference:template:default:includeAutoGeneratedNotice", includeAutoGeneratedNotice.ToString()); // ACT var provider = new ConfigurationProvider(m_ConfigurationFilePath); @@ -319,12 +319,12 @@ public void IncludeAutoGeneratedNotice_can_be_set_in_configuration_file(bool inc // ASSERT Assert.NotNull(config); - Assert.Equal(includeAutoGeneratedNotice, config.IncludeAutoGeneratedNotice); + Assert.Equal(includeAutoGeneratedNotice, config.Template.Default.IncludeAutoGeneratedNotice); } private class TestClass4 { - [ConfigurationValue("mddocs:apireference:includeAutoGeneratedNotice")] + [ConfigurationValue("mddocs:apireference:template:default:includeAutoGeneratedNotice")] public bool IncludeAutoGeneratedNotice { get; set; } } @@ -341,7 +341,7 @@ public void IncludeAutoGeneratedNotice_can_be_set_through_settings_object(bool i // ASSERT Assert.NotNull(config); - Assert.Equal(includeAutoGeneratedNotice, config.IncludeAutoGeneratedNotice); + Assert.Equal(includeAutoGeneratedNotice, config.Template.Default.IncludeAutoGeneratedNotice); } } } diff --git a/src/MdDocs.ApiReference.Test/Templates/Default/PageTestBase.cs b/src/MdDocs.ApiReference.Test/Templates/Default/PageTestBase.cs index c05ac2f5..bbe8b25f 100644 --- a/src/MdDocs.ApiReference.Test/Templates/Default/PageTestBase.cs +++ b/src/MdDocs.ApiReference.Test/Templates/Default/PageTestBase.cs @@ -49,7 +49,7 @@ public void GetDocument_returns_expected_Markdown_for_default_settings() public void GetDocument_does_not_include_AutoGenerated_notice_if_the_includeAutoGeneratedNotice_setting_is_false() { var configuration = new ConfigurationProvider().GetDefaultApiReferenceConfiguration(); - configuration.IncludeAutoGeneratedNotice = false; + configuration.Template.Default.IncludeAutoGeneratedNotice = false; var model = CreateSampleModel(); Approve(model, configuration); } @@ -58,7 +58,7 @@ public void GetDocument_does_not_include_AutoGenerated_notice_if_the_includeAuto public void GetDocument_returns_document_that_does_not_include_the_assembly_version_if_the_includeVersion_setting_is_false() { var configuration = new ConfigurationProvider().GetDefaultApiReferenceConfiguration(); - configuration.IncludeVersion = false; + configuration.Template.Default.IncludeVersion = false; var model = CreateSampleModel(); Approve(model, configuration); } diff --git a/src/MdDocs.ApiReference/Configuration/ApiReferenceConfiguration.cs b/src/MdDocs.ApiReference/Configuration/ApiReferenceConfiguration.cs index 52993b93..a3e62f05 100644 --- a/src/MdDocs.ApiReference/Configuration/ApiReferenceConfiguration.cs +++ b/src/MdDocs.ApiReference/Configuration/ApiReferenceConfiguration.cs @@ -11,6 +11,10 @@ public enum TemplateName public class DefaultTemplateConfiguration : IConfigurationWithMarkdownPresetSetting { + public bool IncludeAutoGeneratedNotice { get; set; } + + public bool IncludeVersion { get; set; } + public MarkdownPreset MarkdownPreset { get; set; } = MarkdownPreset.Default; } @@ -28,11 +32,6 @@ public class TemplateConfiguration [ConvertToFullPath] public string AssemblyPath { get; set; } = ""; - - public bool IncludeAutoGeneratedNotice { get; set; } - - public bool IncludeVersion { get; set; } - public TemplateConfiguration Template { get; set; } = new TemplateConfiguration(); } } diff --git a/src/MdDocs.ApiReference/Templates/Default/MemberPage.cs b/src/MdDocs.ApiReference/Templates/Default/MemberPage.cs index 0d913d83..09acf0bc 100644 --- a/src/MdDocs.ApiReference/Templates/Default/MemberPage.cs +++ b/src/MdDocs.ApiReference/Templates/Default/MemberPage.cs @@ -21,7 +21,7 @@ protected void AddDeclaringTypeSection(MdContainerBlock block) new MdStrongEmphasisSpan("Assembly:"), " " + Model.GetAssemblyDocumentation().Name ); - if (m_Configuration.IncludeVersion) + if (m_Configuration.Template.Default.IncludeVersion) { paragraph.Add("\r\n"); paragraph.Add(new MdCompositeSpan( diff --git a/src/MdDocs.ApiReference/Templates/Default/NamespacePage.cs b/src/MdDocs.ApiReference/Templates/Default/NamespacePage.cs index 37a68729..259cdf32 100644 --- a/src/MdDocs.ApiReference/Templates/Default/NamespacePage.cs +++ b/src/MdDocs.ApiReference/Templates/Default/NamespacePage.cs @@ -28,7 +28,7 @@ internal NamespacePage(ILinkProvider linkProvider, ApiReferenceConfiguration con internal override MdDocument GetDocument() { var document = new MdDocument() - .AddIf(m_Configuration.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) + .AddIf(m_Configuration.Template.Default.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) .Add(new MdHeading($"{Model.Name} Namespace", 1)); diff --git a/src/MdDocs.ApiReference/Templates/Default/OverloadableMemberPage.cs b/src/MdDocs.ApiReference/Templates/Default/OverloadableMemberPage.cs index b82d4ff4..8a374fe0 100644 --- a/src/MdDocs.ApiReference/Templates/Default/OverloadableMemberPage.cs +++ b/src/MdDocs.ApiReference/Templates/Default/OverloadableMemberPage.cs @@ -215,7 +215,7 @@ protected virtual void AddSeeAlsoSubSection(MdContainerBlock block, TOverload ov internal override MdDocument GetDocument() { var document = new MdDocument() - .AddIf(m_Configuration.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) + .AddIf(m_Configuration.Template.Default.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) .Add(GetPageHeading()); diff --git a/src/MdDocs.ApiReference/Templates/Default/SimpleMemberPage.cs b/src/MdDocs.ApiReference/Templates/Default/SimpleMemberPage.cs index 9fe459dd..cd87433b 100644 --- a/src/MdDocs.ApiReference/Templates/Default/SimpleMemberPage.cs +++ b/src/MdDocs.ApiReference/Templates/Default/SimpleMemberPage.cs @@ -28,7 +28,7 @@ internal SimpleMemberPage(ILinkProvider linkProvider, ApiReferenceConfiguration internal override MdDocument GetDocument() { var document = new MdDocument() - .AddIf(m_Configuration.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) + .AddIf(m_Configuration.Template.Default.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) .Add(GetHeading()); AddObsoleteWarning(document.Root, Model); diff --git a/src/MdDocs.ApiReference/Templates/Default/TypePage.cs b/src/MdDocs.ApiReference/Templates/Default/TypePage.cs index 123d2916..3fc37d17 100644 --- a/src/MdDocs.ApiReference/Templates/Default/TypePage.cs +++ b/src/MdDocs.ApiReference/Templates/Default/TypePage.cs @@ -30,7 +30,7 @@ internal TypePage(ILinkProvider linkProvider, ApiReferenceConfiguration configur internal override MdDocument GetDocument() { var document = new MdDocument() - .AddIf(m_Configuration.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) + .AddIf(m_Configuration.Template.Default.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) .Add(new MdHeading($"{Model.DisplayName} {Model.Kind}", 1)); AddObsoleteWarning(document.Root, Model); @@ -93,7 +93,7 @@ private void AddDefinitionSection(MdContainerBlock block) infoParagraph.Add(new MdCompositeSpan(new MdStrongEmphasisSpan("Assembly:"), " " + Model.GetAssemblyDocumentation().Name)); // add assembly version - if (m_Configuration.IncludeVersion) + if (m_Configuration.Template.Default.IncludeVersion) { infoParagraph.Add("\r\n"); infoParagraph.Add(new MdCompositeSpan(new MdStrongEmphasisSpan("Assembly Version:"), " " + Model.GetAssemblyDocumentation().Version)); diff --git a/src/MdDocs.CommandLineHelp.Test/Configuration/CommandLineHelpConfigurationTest.cs b/src/MdDocs.CommandLineHelp.Test/Configuration/CommandLineHelpConfigurationTest.cs index 9590366a..5e0deee1 100644 --- a/src/MdDocs.CommandLineHelp.Test/Configuration/CommandLineHelpConfigurationTest.cs +++ b/src/MdDocs.CommandLineHelp.Test/Configuration/CommandLineHelpConfigurationTest.cs @@ -78,12 +78,12 @@ static object[] TestCase(Action assertion) yield return TestCase(config => Assert.NotNull(config)); yield return TestCase(config => Assert.Empty(config.OutputPath)); - yield return TestCase(config => Assert.True(config.IncludeVersion)); yield return TestCase(config => Assert.Empty(config.AssemblyPath)); - yield return TestCase(config => Assert.True(config.IncludeAutoGeneratedNotice)); yield return TestCase(config => Assert.NotNull(config.Template)); yield return TestCase(config => Assert.Equal(CommandLineHelpConfiguration.TemplateName.Default, config.Template.Name)); yield return TestCase(config => Assert.NotNull(config.Template.Default)); + yield return TestCase(config => Assert.True(config.Template.Default.IncludeVersion)); + yield return TestCase(config => Assert.True(config.Template.Default.IncludeAutoGeneratedNotice)); yield return TestCase(config => Assert.Equal(MarkdownPreset.Default, config.Template.Default.MarkdownPreset)); } @@ -134,7 +134,7 @@ public void GetConfiguration_returns_default_configuration_if_config_file_path_i public void IncludeVersion_can_be_set_in_configuration_file(bool includeVersion) { // ARRANGE - PrepareConfiguration("commandlinehelp:includeversion", includeVersion); + PrepareConfiguration("commandlinehelp:template:default:includeversion", includeVersion); // ACT var provider = new ConfigurationProvider(m_ConfigurationFilePath); @@ -142,12 +142,12 @@ public void IncludeVersion_can_be_set_in_configuration_file(bool includeVersion) // ASSERT Assert.NotNull(config); - Assert.Equal(includeVersion, config.IncludeVersion); + Assert.Equal(includeVersion, config.Template.Default.IncludeVersion); } private class TestClass1 { - [ConfigurationValue("mddocs:commandlinehelp:includeversion")] + [ConfigurationValue("mddocs:commandlinehelp:template:default:includeversion")] public bool? IncludeVersion { get; set; } } @@ -165,7 +165,7 @@ public void IncludeVersion_can_be_set_through_settings_object(bool includeVersio // ASSERT Assert.NotNull(config); - Assert.Equal(includeVersion, config.IncludeVersion); + Assert.Equal(includeVersion, config.Template.Default.IncludeVersion); } @@ -349,7 +349,7 @@ public void GetConfiguration_does_not_change_the_assembly_path_if_value_is_a_roo public void IncludeAutoGeneratedNotice_can_be_set_in_configuration_file(bool includeAutoGeneratedNotice) { // ARRANGE - PrepareConfiguration("commandlinehelp:includeAutoGeneratedNotice", includeAutoGeneratedNotice); + PrepareConfiguration("commandlinehelp:template:default:includeAutoGeneratedNotice", includeAutoGeneratedNotice); // ACT var provider = new ConfigurationProvider(m_ConfigurationFilePath); @@ -357,12 +357,12 @@ public void IncludeAutoGeneratedNotice_can_be_set_in_configuration_file(bool inc // ASSERT Assert.NotNull(config); - Assert.Equal(includeAutoGeneratedNotice, config.IncludeAutoGeneratedNotice); + Assert.Equal(includeAutoGeneratedNotice, config.Template.Default.IncludeAutoGeneratedNotice); } private class TestClass8 { - [ConfigurationValue("mddocs:commandlinehelp:includeAutoGeneratedNotice")] + [ConfigurationValue("mddocs:commandlinehelp:template:default:includeAutoGeneratedNotice")] public bool IncludeAutoGeneratedNotice { get; set; } } @@ -379,7 +379,7 @@ public void IncludeAutoGeneratedNotice_can_be_set_through_settings_object(bool i // ASSERT Assert.NotNull(config); - Assert.Equal(includeAutoGeneratedNotice, config.IncludeAutoGeneratedNotice); + Assert.Equal(includeAutoGeneratedNotice, config.Template.Default.IncludeAutoGeneratedNotice); } } } diff --git a/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/CommandPageTest.cs b/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/CommandPageTest.cs index d49ec27e..c2582e0c 100644 --- a/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/CommandPageTest.cs +++ b/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/CommandPageTest.cs @@ -183,7 +183,7 @@ public void GetDocument_returns_expected_document_12() .WithNamedParameter(shortName: "a"); var configuration = new ConfigurationProvider().GetDefaultCommandLineHelpConfiguration(); - configuration.IncludeVersion = false; + configuration.Template.Default.IncludeVersion = false; Approve(model, configuration); } @@ -220,7 +220,7 @@ public void GetDocument_returns_expected_Markdown_for_default_settings() public void GetDocument_does_not_include_AutoGenerated_notice_if_the_includeAutoGeneratedNotice_setting_is_false() { var configuration = new ConfigurationProvider().GetDefaultCommandLineHelpConfiguration(); - configuration.IncludeAutoGeneratedNotice = false; + configuration.Template.Default.IncludeAutoGeneratedNotice = false; var model = m_ApplicationDocumentation .AddCommand("CommandName") diff --git a/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/MultiCommandApplicationPageTest.cs b/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/MultiCommandApplicationPageTest.cs index 31913ab1..394aa41e 100644 --- a/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/MultiCommandApplicationPageTest.cs +++ b/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/MultiCommandApplicationPageTest.cs @@ -68,7 +68,7 @@ public void GetDocument_returns_expected_document_05() public void GetDocument_returns_expected_document_06() { var configuration = new ConfigurationProvider().GetDefaultCommandLineHelpConfiguration(); - configuration.IncludeVersion = false; + configuration.Template.Default.IncludeVersion = false; var model = new MultiCommandApplicationDocumentation(name: "TestApp", version: "4.5.6") { @@ -95,7 +95,7 @@ public void GetDocument_returns_expected_Markdown_for_default_settings() public void GetDocument_does_not_include_AutoGenerated_notice_if_the_includeAutoGeneratedNotice_setting_is_false() { var configuration = new ConfigurationProvider().GetDefaultCommandLineHelpConfiguration(); - configuration.IncludeAutoGeneratedNotice = false; + configuration.Template.Default.IncludeAutoGeneratedNotice = false; var model = new MultiCommandApplicationDocumentation(name: "TestApp", version: "4.5.6") { diff --git a/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/SingleCommandApplicationPageTest.cs b/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/SingleCommandApplicationPageTest.cs index 86b7511b..42950c1d 100644 --- a/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/SingleCommandApplicationPageTest.cs +++ b/src/MdDocs.CommandLineHelp.Test/Templates/Default/_Documents/SingleCommandApplicationPageTest.cs @@ -41,7 +41,7 @@ public void GetDocument_returns_expected_document_01() public void GetDocument_returns_expected_document_02() { var configuration = new ConfigurationProvider().GetDefaultCommandLineHelpConfiguration(); - configuration.IncludeVersion = false; + configuration.Template.Default.IncludeVersion = false; var application = new SingleCommandApplicationDocumentation(name: "TestApp", "1.2.3") { @@ -70,7 +70,7 @@ public void GetDocument_returns_expected_Markdown_for_default_settings() public void GetDocument_does_not_include_AutoGenerated_notice_if_the_includeAutoGeneratedNotice_setting_is_false() { var configuration = new ConfigurationProvider().GetDefaultCommandLineHelpConfiguration(); - configuration.IncludeAutoGeneratedNotice = false; + configuration.Template.Default.IncludeAutoGeneratedNotice = false; var application = new SingleCommandApplicationDocumentation(name: "TestApp", "1.2.3") { diff --git a/src/MdDocs.CommandLineHelp/Configuration/CommandLineHelpConfiguration.cs b/src/MdDocs.CommandLineHelp/Configuration/CommandLineHelpConfiguration.cs index 351a1b73..d1253ed2 100644 --- a/src/MdDocs.CommandLineHelp/Configuration/CommandLineHelpConfiguration.cs +++ b/src/MdDocs.CommandLineHelp/Configuration/CommandLineHelpConfiguration.cs @@ -11,6 +11,10 @@ public enum TemplateName public class DefaultTemplateConfiguration : IConfigurationWithMarkdownPresetSetting { + public bool IncludeVersion { get; set; } + + public bool IncludeAutoGeneratedNotice { get; set; } + public MarkdownPreset MarkdownPreset { get; set; } = MarkdownPreset.Default; } @@ -26,13 +30,9 @@ public class TemplateConfiguration [ConvertToFullPath] public string OutputPath { get; set; } = ""; - public bool IncludeVersion { get; set; } - [ConvertToFullPath] public string AssemblyPath { get; set; } = ""; - public bool IncludeAutoGeneratedNotice { get; set; } - public TemplateConfiguration Template { get; set; } = new TemplateConfiguration(); } } diff --git a/src/MdDocs.CommandLineHelp/Templates/Default/_Documents/CommandPage.cs b/src/MdDocs.CommandLineHelp/Templates/Default/_Documents/CommandPage.cs index 388efc3c..006a7ea4 100644 --- a/src/MdDocs.CommandLineHelp/Templates/Default/_Documents/CommandPage.cs +++ b/src/MdDocs.CommandLineHelp/Templates/Default/_Documents/CommandPage.cs @@ -42,7 +42,7 @@ public CommandPage(DocumentSet documentSet, ICommandLineHelpPathProvi internal MdDocument GetDocument() { return new MdDocument() - .AddIf(m_Conifguration.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) + .AddIf(m_Conifguration.Template.Default.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) // Heading .Add(new MdHeading(1, new MdCompositeSpan(new MdCodeSpan(m_Command.Name), " Command"))) // add application info @@ -70,7 +70,7 @@ private MdBlock GetApplicationInfo() link }; - if (m_Conifguration.IncludeVersion && !String.IsNullOrEmpty(m_Command.Application.Version)) + if (m_Conifguration.Template.Default.IncludeVersion && !String.IsNullOrEmpty(m_Command.Application.Version)) { span.Add(new MdRawMarkdownSpan("\r\n")); span.Add(new MdStrongEmphasisSpan("Version:")); diff --git a/src/MdDocs.CommandLineHelp/Templates/Default/_Documents/MultiCommandApplicationPage.cs b/src/MdDocs.CommandLineHelp/Templates/Default/_Documents/MultiCommandApplicationPage.cs index 975afbb2..9212d815 100644 --- a/src/MdDocs.CommandLineHelp/Templates/Default/_Documents/MultiCommandApplicationPage.cs +++ b/src/MdDocs.CommandLineHelp/Templates/Default/_Documents/MultiCommandApplicationPage.cs @@ -47,11 +47,11 @@ public MultiCommandApplicationPage( internal MdDocument GetDocument() { return new MdDocument() - .AddIf(m_Configuration.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) + .AddIf(m_Configuration.Template.Default.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) // Application name and version .Add(new MdHeading(1, $"{m_Model.Name} Command Line Reference")) - .AddIf(m_Configuration.IncludeVersion, new ApplicationVersionBlock(m_Model)) + .AddIf(m_Configuration.Template.Default.IncludeVersion, new ApplicationVersionBlock(m_Model)) // Usage (data from ApplicationUsage attribute) .AddIf(m_Model.Usage?.Count > 0, new MdHeading(2, "Usage")) diff --git a/src/MdDocs.CommandLineHelp/Templates/Default/_Documents/SingleCommandApplicationPage.cs b/src/MdDocs.CommandLineHelp/Templates/Default/_Documents/SingleCommandApplicationPage.cs index acc2c300..4db6aa78 100644 --- a/src/MdDocs.CommandLineHelp/Templates/Default/_Documents/SingleCommandApplicationPage.cs +++ b/src/MdDocs.CommandLineHelp/Templates/Default/_Documents/SingleCommandApplicationPage.cs @@ -49,11 +49,11 @@ public SingleCommandApplicationPage( internal MdDocument GetDocument() { return new MdDocument() - .AddIf(m_Configuration.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) + .AddIf(m_Configuration.Template.Default.IncludeAutoGeneratedNotice, new AutoGeneratedNotice()) // Application name and version .Add(new MdHeading(1, $"{m_Model.Name} Command Line Reference")) - .AddIf(m_Configuration.IncludeVersion, new ApplicationVersionBlock(m_Model)) + .AddIf(m_Configuration.Template.Default.IncludeVersion, new ApplicationVersionBlock(m_Model)) // Usage (data from ApplicationUsage attribute) .AddIf(m_Model.Usage != null && m_Model.Usage.Count > 0, new MdHeading(2, "Usage")) diff --git a/src/MdDocs.Common/Configuration/defaultSettings.json b/src/MdDocs.Common/Configuration/defaultSettings.json index c6474403..5e4983a1 100644 --- a/src/MdDocs.Common/Configuration/defaultSettings.json +++ b/src/MdDocs.Common/Configuration/defaultSettings.json @@ -5,11 +5,11 @@ "commandlinehelp" : { "assemblyPath" : null, "outputPath" : null, - "includeVersion" : true, - "includeAutoGeneratedNotice" : true, "template": { "name": "Default", "default": { + "includeVersion" : true, + "includeAutoGeneratedNotice" : true, "markdownPreset" : "Default" } } @@ -18,11 +18,11 @@ "apireference" : { "assemblyPath" : null, "outputPath": null, - "includeVersion" : true, - "includeAutoGeneratedNotice" : true, "template": { "name": "Default", "default": { + "includeVersion" : true, + "includeAutoGeneratedNotice" : true, "markdownPreset" : "Default" } } diff --git a/src/MdDocs.MSBuild.Test/GenerateApiReferenceDocumentationTest.cs b/src/MdDocs.MSBuild.Test/GenerateApiReferenceDocumentationTest.cs index 5e2c371a..9705c125 100644 --- a/src/MdDocs.MSBuild.Test/GenerateApiReferenceDocumentationTest.cs +++ b/src/MdDocs.MSBuild.Test/GenerateApiReferenceDocumentationTest.cs @@ -87,25 +87,6 @@ public void OutputDirectoryPath_overrides_output_path_setting() Assert.Equal(expectedOutputPath, config.OutputPath); } - [Theory] - [CombinatorialData] - public void MarkdownPreset_property_overrides_configuration_of_markdown_preset(MarkdownPreset preset) - { - // ARRANGE - var sut = new GenerateApiReferenceDocumentation() - { - Assembly = new TaskItem("myAssembly.dll"), - BuildEngine = new BuildEngineMock(), - MarkdownPreset = preset.ToString() - }; - - // ACT - var config = sut.GetConfigurationProvider().GetApiReferenceConfiguration(); - - // ASSERT - Assert.Equal(preset, config.Template.Default.MarkdownPreset); - } - [Theory] [CombinatorialData] public void LoadConfiguration_file_reads_configuration_file_if_path_is_specified(MarkdownPreset preset) @@ -131,7 +112,6 @@ public void LoadConfiguration_file_reads_configuration_file_if_path_is_specified BuildEngine = new BuildEngineMock(), OutputDirectory = new TaskItem("my-output-directory"), ConfigurationFile = new TaskItem(configPath), - MarkdownPreset = null }; // ACT diff --git a/src/MdDocs.MSBuild.Test/GenerateCommandLineDocumentationTest.cs b/src/MdDocs.MSBuild.Test/GenerateCommandLineDocumentationTest.cs index 463cc068..df6366ea 100644 --- a/src/MdDocs.MSBuild.Test/GenerateCommandLineDocumentationTest.cs +++ b/src/MdDocs.MSBuild.Test/GenerateCommandLineDocumentationTest.cs @@ -87,46 +87,6 @@ public void OutputDirectoryPath_overrides_output_path_setting() Assert.Equal(expectedOutputPath, config.OutputPath); } - [Theory] - [CombinatorialData] - public void IncludeVersion_overrides_include_version_setting(bool includeVersion) - { - // ARRANGE - var sut = new GenerateCommandLineDocumentation() - { - Assembly = new TaskItem("my-assembly.dll"), - BuildEngine = new BuildEngineMock(), - IncludeVersion = includeVersion - }; - - - // ACT - var config = sut.GetConfigurationProvider().GetCommandLineHelpConfiguration(); - - // ASSERT - Assert.Equal(includeVersion, config.IncludeVersion); - } - - - [Theory] - [CombinatorialData] - public void MarkdownPreset_property_overrides_configuration_of_markdown_preset(MarkdownPreset preset) - { - // ARRANGE - var sut = new GenerateCommandLineDocumentation() - { - Assembly = new TaskItem("myAssembly.dll"), - BuildEngine = new BuildEngineMock(), - MarkdownPreset = preset.ToString() - }; - - // ACT - var config = sut.GetConfigurationProvider().GetCommandLineHelpConfiguration(); - - // ASSERT - Assert.Equal(preset, config.Template.Default.MarkdownPreset); - } - [Theory] [CombinatorialData] public void LoadConfiguration_file_reads_configuration_file_if_path_is_specified(MarkdownPreset preset) @@ -151,8 +111,7 @@ public void LoadConfiguration_file_reads_configuration_file_if_path_is_specified Assembly = new TaskItem("myAssembly.dll"), BuildEngine = new BuildEngineMock(), OutputDirectory = new TaskItem("my-output-directory"), - ConfigurationFile = new TaskItem(configPath), - MarkdownPreset = null + ConfigurationFile = new TaskItem(configPath) }; // ACT diff --git a/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.props b/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.props index c5315058..a267c2b7 100644 --- a/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.props +++ b/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.props @@ -17,8 +17,7 @@ false - false - + false $([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildProjectDirectory), mddocs.settings.json))\mddocs.settings.json diff --git a/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.targets b/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.targets index 102b1719..3d11d60f 100644 --- a/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.targets +++ b/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.targets @@ -11,7 +11,6 @@ @@ -40,7 +39,6 @@ diff --git a/src/MdDocs.MSBuild/src/GenerateApiReferenceDocumentation.cs b/src/MdDocs.MSBuild/src/GenerateApiReferenceDocumentation.cs index a9ca8915..bfb4168e 100644 --- a/src/MdDocs.MSBuild/src/GenerateApiReferenceDocumentation.cs +++ b/src/MdDocs.MSBuild/src/GenerateApiReferenceDocumentation.cs @@ -12,9 +12,6 @@ public sealed class GenerateApiReferenceDocumentation : TaskBase [ConfigurationValue("mddocs:apireference:outputPath")] public string OutputDirectoryPath => OutputDirectory?.GetFullPath() ?? ""; - [ConfigurationValue("mddocs:apireference:template:default:markdownPreset")] - public string? MarkdownPreset { get; set; } - public override bool Execute() { diff --git a/src/MdDocs.MSBuild/src/GenerateCommandLineDocumentation.cs b/src/MdDocs.MSBuild/src/GenerateCommandLineDocumentation.cs index 3ad4f614..a07bbd7c 100644 --- a/src/MdDocs.MSBuild/src/GenerateCommandLineDocumentation.cs +++ b/src/MdDocs.MSBuild/src/GenerateCommandLineDocumentation.cs @@ -12,13 +12,6 @@ public sealed class GenerateCommandLineDocumentation : TaskBase [ConfigurationValue("mddocs:commandlinehelp:outputPath")] public string OutputDirectoryPath => OutputDirectory?.GetFullPath() ?? ""; - [ConfigurationValue("mddocs:commandlinehelp:includeVersion")] - public bool IncludeVersion { get; set; } = true; - - [ConfigurationValue("mddocs:commandlinehelp:template:default:markdownPreset")] - public string? MarkdownPreset { get; set; } - - public override bool Execute() { if (!ValidateParameters()) diff --git a/src/MdDocs.Test/ApiReferenceOptionsTest.cs b/src/MdDocs.Test/ApiReferenceOptionsTest.cs index 45caa5f6..29bb3987 100644 --- a/src/MdDocs.Test/ApiReferenceOptionsTest.cs +++ b/src/MdDocs.Test/ApiReferenceOptionsTest.cs @@ -67,23 +67,5 @@ public void AssemblyPath_does_not_convert_value_to_a_absolute_path_if_path_is_nu // ACT / ASSERT Assert.Equal(path, sut.AssemblyPath); } - - [Theory] - [InlineData(true, true)] - [InlineData(false, null)] - public void IncludeVersion_returns_expected_value_based_on_the_no_version_flag(bool noVersion, bool? expected) - { - // ARRANGE - var sut = new ApiReferenceOptions() - { - NoVersion = noVersion - }; - - // ACT - var actual = sut.IncludeVersion; - - // ASSERT - Assert.Equal(expected, actual); - } } } diff --git a/src/MdDocs.Test/CommandLineHelpOptionsTest.cs b/src/MdDocs.Test/CommandLineHelpOptionsTest.cs index 0e482eb7..ead58616 100644 --- a/src/MdDocs.Test/CommandLineHelpOptionsTest.cs +++ b/src/MdDocs.Test/CommandLineHelpOptionsTest.cs @@ -8,24 +8,6 @@ namespace Grynwald.MdDocs.Test /// public class CommandLineHelpOptionsTest { - [Theory] - [InlineData(true, true)] - [InlineData(false, null)] - public void IncludeVersion_returns_expected_value_based_on_the_no_version_flag(bool noVersion, bool? expected) - { - // ARRANGE - var sut = new CommandLineHelpOptions() - { - NoVersion = noVersion - }; - - // ACT - var actual = sut.IncludeVersion; - - // ASSERT - Assert.Equal(expected, actual); - } - [Fact] public void OutputDirectory_converts_value_to_a_absolute_path() { diff --git a/src/MdDocs.Test/CommandLineTests.cs b/src/MdDocs.Test/CommandLineTests.cs index 79577dc4..7d279372 100644 --- a/src/MdDocs.Test/CommandLineTests.cs +++ b/src/MdDocs.Test/CommandLineTests.cs @@ -18,16 +18,11 @@ private static bool IsConfigurationProperty(Type type, string propertyName) return (type.Name, propertyName) switch { (_, nameof(OptionsBase.Verbose)) => false, - (_, nameof(OptionsBase.MarkdownPreset)) => true, (_, nameof(OptionsBase.ConfigurationFilePath)) => false, (nameof(CommandLineHelpOptions), nameof(OptionsBase.OutputDirectory)) => true, (nameof(CommandLineHelpOptions), nameof(CommandLineHelpOptions.AssemblyPath)) => true, - (nameof(CommandLineHelpOptions), nameof(CommandLineHelpOptions.NoVersion)) => false, - (nameof(CommandLineHelpOptions), nameof(CommandLineHelpOptions.IncludeVersion)) => true, (nameof(ApiReferenceOptions), nameof(ApiReferenceOptions.AssemblyPath)) => true, (nameof(ApiReferenceOptions), nameof(OptionsBase.OutputDirectory)) => true, - (nameof(ApiReferenceOptions), nameof(CommandLineHelpOptions.NoVersion)) => false, - (nameof(ApiReferenceOptions), nameof(CommandLineHelpOptions.IncludeVersion)) => true, _ => throw new NotImplementedException() }; } diff --git a/src/MdDocs/ApiReferenceOptions.cs b/src/MdDocs/ApiReferenceOptions.cs index 6f787f64..7888a03f 100644 --- a/src/MdDocs/ApiReferenceOptions.cs +++ b/src/MdDocs/ApiReferenceOptions.cs @@ -30,13 +30,5 @@ public override string? OutputDirectory get => base.OutputDirectory; set => base.OutputDirectory = value; } - - - [Option("no-version", Required = false, HelpText = "Do not include the assembly version in the generated documentation.")] - public bool NoVersion { get; set; } - - [ConfigurationValue("mddocs:apireference:includeAutoGeneratedNotice")] - public bool? IncludeVersion => NoVersion ? (bool?)true : null; - } } diff --git a/src/MdDocs/CommandLineHelpOptions.cs b/src/MdDocs/CommandLineHelpOptions.cs index 342ae753..e670f12d 100644 --- a/src/MdDocs/CommandLineHelpOptions.cs +++ b/src/MdDocs/CommandLineHelpOptions.cs @@ -24,12 +24,6 @@ public string? AssemblyPath set => m_AssemblyPath = value; } - [Option("no-version", Required = false, HelpText = "Do not include the application version in the generated documentation.")] - public bool NoVersion { get; set; } - - [ConfigurationValue("mddocs:commandlinehelp:includeVersion")] - public bool? IncludeVersion => NoVersion ? (bool?)true : null; - [ConfigurationValue("mddocs:commandlinehelp:outputPath")] public override string? OutputDirectory { diff --git a/src/MdDocs/OptionsBase.cs b/src/MdDocs/OptionsBase.cs index 639c36d3..8eb2ecc2 100644 --- a/src/MdDocs/OptionsBase.cs +++ b/src/MdDocs/OptionsBase.cs @@ -26,12 +26,6 @@ public virtual string? OutputDirectory set => m_OutputDirectory = value; } - [Option("markdown-preset", - Required = false, - Default = MarkdownPreset.Default, - HelpText = "Specifies the preset to use for generating Markdown files.")] - [ConfigurationValue("mddocs:markdown:preset")] - public MarkdownPreset MarkdownPreset { get; set; } [Option('c', "configurationFilePath", Required = false, HelpText = "The path of the configuration file to use. " +