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.
ap0llo · Jun 20, 2020 · 8276402 · 8276402
1 parent e454742
commit 8276402
Show file tree

Hide file tree

Showing 33 changed files with 102 additions and 285 deletions.
diff --git 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 <VALUE>]
                     [--configurationFilePath|-c <VALUE>]
-                    [--markdown-preset <VALUE>]
                     [--outdir|-o <VALUE>]
-                    [--no-version]
                     [--verbose|-v]
 ```
 
@@ -28,9 +26,7 @@ mddocs apireference [--assembly|-a <VALUE>]
 | --------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
 | [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
@@ -16,9 +16,7 @@ Generate command line help for .NET console application implemented using the 'C
 ```
 mddocs commandlinehelp [--assembly|-a <VALUE>]
                        [--configurationFilePath|-c <VALUE>]
-                       [--markdown-preset <VALUE>]
                        [--outdir|-o <VALUE>]
-                       [--no-version]
                        [--verbose|-v]
 ```
 
@@ -28,9 +26,7 @@ mddocs commandlinehelp [--assembly|-a <VALUE>]
 | --------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
 | [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
@@ -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
@@ -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
         }
     }
 }
diff --git a/src/MdDocs.ApiReference.Test/Configuration/ApiReferenceConfigurationTest.cs b/src/MdDocs.ApiReference.Test/Configuration/ApiReferenceConfigurationTest.cs
@@ -79,11 +79,11 @@ static object[] TestCase(Action<ApiReferenceConfiguration> 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,20 +311,20 @@ 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);
             var config = provider.GetApiReferenceConfiguration();
 
             // 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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());