Skip to content

Commit 8276402

Browse files
ap0lloap0llo
committed
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.
1 parent e454742 commit 8276402

33 files changed

+102
-285
lines changed

‎docs/commandline/commands/apireference.md

-31
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,7 @@ Generate API reference documentation for a .NET assembly.
1616
```
1717
mddocs apireference [--assembly|-a <VALUE>]
1818
[--configurationFilePath|-c <VALUE>]
19-
[--markdown-preset <VALUE>]
2019
[--outdir|-o <VALUE>]
21-
[--no-version]
2220
[--verbose|-v]
2321
```
2422

@@ -28,9 +26,7 @@ mddocs apireference [--assembly|-a <VALUE>]
2826
| --------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
2927
| [assembly](#assembly-parameter) | [a](#assembly-parameter) | Path of the assembly to generate documentation for. |
3028
| [configurationFilePath](#configurationfilepath-parameter) | [c](#configurationfilepath-parameter) | The path of the configuration file to use. If no configuration file is specified, default settings are used. |
31-
| [markdown\-preset](#markdownpreset-parameter) | | Specifies the preset to use for generating Markdown files. |
3229
| [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. |
33-
| [no\-version](#noversion-parameter) | | Do not include the assembly version in the generated documentation. |
3430
| [verbose](#verbose-parameter) | [v](#verbose-parameter) | Show more detailed log output. |
3531

3632
### `assembly` Parameter
@@ -61,20 +57,6 @@ The path of the configuration file to use. If no configuration file is specified
6157

6258
___
6359

64-
### `markdown-preset` Parameter
65-
66-
Specifies the preset to use for generating Markdown files.
67-
68-
| | |
69-
| ---------------- | ------------------- |
70-
| Name: | markdown\-preset |
71-
| Position: | *Named parameter* |
72-
| Required: | No |
73-
| Accepted values: | `Default`, `MkDocs` |
74-
| Default value: | `Default` |
75-
76-
___
77-
7860
### `outdir` Parameter
7961

8062
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
8971

9072
___
9173

92-
### `no-version` Parameter
93-
94-
Do not include the assembly version in the generated documentation.
95-
96-
| | |
97-
| -------------- | ------------------------- |
98-
| Name: | no\-version |
99-
| Position: | *None (Switch Parameter)* |
100-
| Required: | *No (Switch Parameter)* |
101-
| Default value: | `false` |
102-
103-
___
104-
10574
### `verbose` Parameter
10675

10776
Show more detailed log output.

‎docs/commandline/commands/commandlinehelp.md

-31
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,7 @@ Generate command line help for .NET console application implemented using the 'C
1616
```
1717
mddocs commandlinehelp [--assembly|-a <VALUE>]
1818
[--configurationFilePath|-c <VALUE>]
19-
[--markdown-preset <VALUE>]
2019
[--outdir|-o <VALUE>]
21-
[--no-version]
2220
[--verbose|-v]
2321
```
2422

@@ -28,9 +26,7 @@ mddocs commandlinehelp [--assembly|-a <VALUE>]
2826
| --------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
2927
| [assembly](#assembly-parameter) | [a](#assembly-parameter) | Path of the command line application assembly to generate documentation for. |
3028
| [configurationFilePath](#configurationfilepath-parameter) | [c](#configurationfilepath-parameter) | The path of the configuration file to use. If no configuration file is specified, default settings are used. |
31-
| [markdown\-preset](#markdownpreset-parameter) | | Specifies the preset to use for generating Markdown files. |
3229
| [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. |
33-
| [no\-version](#noversion-parameter) | | Do not include the application version in the generated documentation. |
3430
| [verbose](#verbose-parameter) | [v](#verbose-parameter) | Show more detailed log output. |
3531

3632
### `assembly` Parameter
@@ -61,20 +57,6 @@ The path of the configuration file to use. If no configuration file is specified
6157

6258
___
6359

64-
### `markdown-preset` Parameter
65-
66-
Specifies the preset to use for generating Markdown files.
67-
68-
| | |
69-
| ---------------- | ------------------- |
70-
| Name: | markdown\-preset |
71-
| Position: | *Named parameter* |
72-
| Required: | No |
73-
| Accepted values: | `Default`, `MkDocs` |
74-
| Default value: | `Default` |
75-
76-
___
77-
7860
### `outdir` Parameter
7961

8062
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
8971

9072
___
9173

92-
### `no-version` Parameter
93-
94-
Do not include the application version in the generated documentation.
95-
96-
| | |
97-
| -------------- | ------------------------- |
98-
| Name: | no\-version |
99-
| Position: | *None (Switch Parameter)* |
100-
| Required: | *No (Switch Parameter)* |
101-
| Default value: | `false` |
102-
103-
___
104-
10574
### `verbose` Parameter
10675

10776
Show more detailed log output.

‎mddocs.settings.json

+12-4
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,22 @@
11
{
2+
"$schema": "./schemas/configuration/schema.json",
23
"mddocs": {
34

45
"commandlinehelp": {
5-
"includeVersion" : false,
6-
"outputPath": "./docs/commandline"
6+
"outputPath": "./docs/commandline",
7+
"template": {
8+
"default": {
9+
"includeVersion" : false
10+
}
11+
}
712
},
813

914
"apireference" : {
10-
"includeVersion" : false
15+
"template": {
16+
"default": {
17+
"includeVersion" : false
18+
}
19+
}
1120
}
12-
1321
}
1422
}

‎schemas/configuration/schema.json

+40-33
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@
2424
"$ref": "#/definitions/commandlinehelpConfiguration",
2525
"title": "Command Line Help Settings"
2626
}
27-
}
27+
},
28+
"additionalProperties": false
2829
},
2930
"commandlinehelpConfiguration": {
3031
"type": "object",
@@ -47,23 +48,12 @@
4748
"title": "Command Line Help: Output Path",
4849
"description": "The directory path to save the generated documentation to."
4950
},
50-
"includeVersion": {
51-
"type": "boolean",
52-
"default": true,
53-
"title": "Command Line Help: Include Version",
54-
"description": "Controls whether the version of the application is included in the generated documentation."
55-
},
56-
"includeAutoGeneratedNotice": {
57-
"type": "boolean",
58-
"default": true,
59-
"title": "Command Line Help: Include AutoGenerated Notice",
60-
"description": "Controls whether the generated documentation includes a comment that indicates the files were auto-generated."
61-
},
6251
"template": {
6352
"$ref": "#/definitions/commandlinehelpTemplateConfiguration",
6453
"description": "Specifies settings for templates."
6554
}
66-
}
55+
},
56+
"additionalProperties": false
6757
},
6858
"commandlinehelpTemplateConfiguration": {
6959
"type": "object",
@@ -80,7 +70,8 @@
8070
"title": "Command Line Help: Default Template Settings",
8171
"description": "Defines settings for the default template"
8272
}
83-
}
73+
},
74+
"additionalProperties": false
8475
},
8576
"commandlinehelpDefaultTemplateConfiguration": {
8677
"type": "object",
@@ -91,10 +82,23 @@
9182
"Default",
9283
"MkDocs"
9384
],
94-
"title": "Command Line Help: Markdown Preset",
85+
"title": "Command Line Help (Default Template): Markdown Preset",
9586
"description": "Customizes serialization of Markdown."
87+
},
88+
"includeVersion": {
89+
"type": "boolean",
90+
"default": true,
91+
"title": "Command Line Help (Default Template): Include Version",
92+
"description": "Controls whether the version of the application is included in the generated documentation."
93+
},
94+
"includeAutoGeneratedNotice": {
95+
"type": "boolean",
96+
"default": true,
97+
"title": "Command Line Help (Default Template): Include AutoGenerated Notice",
98+
"description": "Controls whether the generated documentation includes a comment that indicates the files were auto-generated."
9699
}
97-
}
100+
},
101+
"additionalProperties": false
98102
},
99103
"apireferenceConfiguration": {
100104
"type": "object",
@@ -117,23 +121,12 @@
117121
"title": "API Reference: Output Path",
118122
"description": "The directory path to save the generated documentation to."
119123
},
120-
"includeVersion": {
121-
"type": "boolean",
122-
"default": true,
123-
"title": "API Reference: Include Version",
124-
"description": "Controls whether the version of the assembly is included in the generated documentation."
125-
},
126-
"includeAutoGeneratedNotice": {
127-
"type": "boolean",
128-
"default": true,
129-
"title": "API Reference: Include AutoGenerated Notice",
130-
"description": "Controls whether the generated documentation includes a comment that indicates the files were auto-generated."
131-
},
132124
"template": {
133125
"$ref": "#/definitions/apireferenceTemplateConfiguration",
134126
"description": "Specifies settings for templates."
135127
}
136-
}
128+
},
129+
"additionalProperties": false
137130
},
138131
"apireferenceTemplateConfiguration": {
139132
"type": "object",
@@ -150,7 +143,8 @@
150143
"title": "API Reference: Default Template Settings",
151144
"description": "Defines settings for the default template"
152145
}
153-
}
146+
},
147+
"additionalProperties": false
154148
},
155149
"apireferenceDefaultTemplateConfiguration": {
156150
"type": "object",
@@ -161,10 +155,23 @@
161155
"Default",
162156
"MkDocs"
163157
],
164-
"title": "API Reference: Markdown Preset",
158+
"title": "API Reference (Default Template): Markdown Preset",
165159
"description": "Customizes serialization of Markdown."
160+
},
161+
"includeVersion": {
162+
"type": "boolean",
163+
"default": true,
164+
"title": "API Reference (Default Template): Include Version",
165+
"description": "Controls whether the version of the assembly is included in the generated documentation."
166+
},
167+
"includeAutoGeneratedNotice": {
168+
"type": "boolean",
169+
"default": true,
170+
"title": "API Reference (Default Template): Include AutoGenerated Notice",
171+
"description": "Controls whether the generated documentation includes a comment that indicates the files were auto-generated."
166172
}
167-
}
173+
},
174+
"additionalProperties": false
168175
}
169176
}
170177
}

‎src/MdDocs.ApiReference.Test/Configuration/ApiReferenceConfigurationTest.cs

+6-6
Original file line numberDiff line numberDiff line change
@@ -79,11 +79,11 @@ static object[] TestCase(Action<ApiReferenceConfiguration> assertion)
7979
yield return TestCase(config => Assert.NotNull(config));
8080
yield return TestCase(config => Assert.Empty(config.OutputPath));
8181
yield return TestCase(config => Assert.Empty(config.AssemblyPath));
82-
yield return TestCase(config => Assert.True(config.IncludeAutoGeneratedNotice));
83-
yield return TestCase(config => Assert.True(config.IncludeVersion));
8482
yield return TestCase(config => Assert.NotNull(config.Template));
8583
yield return TestCase(config => Assert.Equal(ApiReferenceConfiguration.TemplateName.Default, config.Template.Name));
8684
yield return TestCase(config => Assert.NotNull(config.Template.Default));
85+
yield return TestCase(config => Assert.True(config.Template.Default.IncludeAutoGeneratedNotice));
86+
yield return TestCase(config => Assert.True(config.Template.Default.IncludeVersion));
8787
yield return TestCase(config => Assert.Equal(MarkdownPreset.Default, config.Template.Default.MarkdownPreset));
8888
}
8989

@@ -311,20 +311,20 @@ public void GetConfiguration_does_not_change_the_assembly_path_if_value_is_a_roo
311311
public void IncludeAutoGeneratedNotice_can_be_set_in_configuration_file(bool includeAutoGeneratedNotice)
312312
{
313313
// ARRANGE
314-
PrepareConfiguration("apireference:includeAutoGeneratedNotice", includeAutoGeneratedNotice.ToString());
314+
PrepareConfiguration("apireference:template:default:includeAutoGeneratedNotice", includeAutoGeneratedNotice.ToString());
315315

316316
// ACT
317317
var provider = new ConfigurationProvider(m_ConfigurationFilePath);
318318
var config = provider.GetApiReferenceConfiguration();
319319

320320
// ASSERT
321321
Assert.NotNull(config);
322-
Assert.Equal(includeAutoGeneratedNotice, config.IncludeAutoGeneratedNotice);
322+
Assert.Equal(includeAutoGeneratedNotice, config.Template.Default.IncludeAutoGeneratedNotice);
323323
}
324324

325325
private class TestClass4
326326
{
327-
[ConfigurationValue("mddocs:apireference:includeAutoGeneratedNotice")]
327+
[ConfigurationValue("mddocs:apireference:template:default:includeAutoGeneratedNotice")]
328328
public bool IncludeAutoGeneratedNotice { get; set; }
329329
}
330330

@@ -341,7 +341,7 @@ public void IncludeAutoGeneratedNotice_can_be_set_through_settings_object(bool i
341341

342342
// ASSERT
343343
Assert.NotNull(config);
344-
Assert.Equal(includeAutoGeneratedNotice, config.IncludeAutoGeneratedNotice);
344+
Assert.Equal(includeAutoGeneratedNotice, config.Template.Default.IncludeAutoGeneratedNotice);
345345
}
346346
}
347347
}

‎src/MdDocs.ApiReference.Test/Templates/Default/PageTestBase.cs

+2-2
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ public void GetDocument_returns_expected_Markdown_for_default_settings()
4949
public void GetDocument_does_not_include_AutoGenerated_notice_if_the_includeAutoGeneratedNotice_setting_is_false()
5050
{
5151
var configuration = new ConfigurationProvider().GetDefaultApiReferenceConfiguration();
52-
configuration.IncludeAutoGeneratedNotice = false;
52+
configuration.Template.Default.IncludeAutoGeneratedNotice = false;
5353
var model = CreateSampleModel();
5454
Approve(model, configuration);
5555
}
@@ -58,7 +58,7 @@ public void GetDocument_does_not_include_AutoGenerated_notice_if_the_includeAuto
5858
public void GetDocument_returns_document_that_does_not_include_the_assembly_version_if_the_includeVersion_setting_is_false()
5959
{
6060
var configuration = new ConfigurationProvider().GetDefaultApiReferenceConfiguration();
61-
configuration.IncludeVersion = false;
61+
configuration.Template.Default.IncludeVersion = false;
6262
var model = CreateSampleModel();
6363
Approve(model, configuration);
6464
}

‎src/MdDocs.ApiReference/Configuration/ApiReferenceConfiguration.cs

+4-5
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,10 @@ public enum TemplateName
1111

1212
public class DefaultTemplateConfiguration : IConfigurationWithMarkdownPresetSetting
1313
{
14+
public bool IncludeAutoGeneratedNotice { get; set; }
15+
16+
public bool IncludeVersion { get; set; }
17+
1418
public MarkdownPreset MarkdownPreset { get; set; } = MarkdownPreset.Default;
1519
}
1620

@@ -28,11 +32,6 @@ public class TemplateConfiguration
2832
[ConvertToFullPath]
2933
public string AssemblyPath { get; set; } = "";
3034

31-
32-
public bool IncludeAutoGeneratedNotice { get; set; }
33-
34-
public bool IncludeVersion { get; set; }
35-
3635
public TemplateConfiguration Template { get; set; } = new TemplateConfiguration();
3736
}
3837
}

‎src/MdDocs.ApiReference/Templates/Default/MemberPage.cs

+1-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ protected void AddDeclaringTypeSection(MdContainerBlock block)
2121
new MdStrongEmphasisSpan("Assembly:"), " " + Model.GetAssemblyDocumentation().Name
2222
);
2323

24-
if (m_Configuration.IncludeVersion)
24+
if (m_Configuration.Template.Default.IncludeVersion)
2525
{
2626
paragraph.Add("\r\n");
2727
paragraph.Add(new MdCompositeSpan(

‎src/MdDocs.ApiReference/Templates/Default/NamespacePage.cs

+1-1
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ internal NamespacePage(ILinkProvider linkProvider, ApiReferenceConfiguration con
2828
internal override MdDocument GetDocument()
2929
{
3030
var document = new MdDocument()
31-
.AddIf(m_Configuration.IncludeAutoGeneratedNotice, new AutoGeneratedNotice())
31+
.AddIf(m_Configuration.Template.Default.IncludeAutoGeneratedNotice, new AutoGeneratedNotice())
3232
.Add(new MdHeading($"{Model.Name} Namespace", 1));
3333

3434

‎src/MdDocs.ApiReference/Templates/Default/OverloadableMemberPage.cs

+1-1
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,7 @@ protected virtual void AddSeeAlsoSubSection(MdContainerBlock block, TOverload ov
215215
internal override MdDocument GetDocument()
216216
{
217217
var document = new MdDocument()
218-
.AddIf(m_Configuration.IncludeAutoGeneratedNotice, new AutoGeneratedNotice())
218+
.AddIf(m_Configuration.Template.Default.IncludeAutoGeneratedNotice, new AutoGeneratedNotice())
219219
.Add(GetPageHeading());
220220

221221

0 commit comments

Comments
 (0)