feat: Add "preset" option to adjust output files to target renderer

Adds the option to specify a "preset" to optimize the generated documents for a specific Markdown renderer. In the commandline version of MdDocs, the perset can be specified Using the '--markdown-preset' parameter, for the MSBuild-integrated version, the preset can be set using the 'MdDocsMarkdownPreset' MSBuild property. The currently only preset other than 'Default' is 'MkDocs', which generates Markdown suited to be included in a MkDocs projects. At the moment the preset does not change the document structure being generated, but uses the corresponding preset from the 'MarkdownGenerator' libary, which adjust the output for MkDocs by: - Increasing the number of characters used to indent nested lists - Changing the escaping of '<' and '>' to '<' respectively '>'
ap0llo · Oct 3, 2019 · 816b902 · 816b902
1 parent 16443eb
commit 816b902
Show file tree

Hide file tree

Showing 11 changed files with 167 additions and 34 deletions.
diff --git a/README.md b/README.md
@@ -102,13 +102,14 @@ To generate API reference for a project, run
 dotnet msbuild <PROJECT> /t:GenerateApiReferenceDocumentation
 ```
 
-By default, the API reference will be saved to `$(OutputPath)docs/api/`.
-The output path can be customized by setting the MSBuild property
-`ApiReferenceDocumentationOutputPath`.
+The behaviour of the target can be customized by setting the following
+MSBuild properties:
 
-To automatically generate API documentation when the project is built,
-set the property `GenerateApiReferenceDocumentationOnBuild` to `true`
-(default: `false`).
+| Property Name                              | Default Value            | Description                                                                               |
+|--------------------------------------------|--------------------------|-------------------------------------------------------------------------------------------|
+| `ApiReferenceDocumentationOutputPath`      | `$(OutputPath)docs/api/` | The directory to save the generated documetation to.                                      |
+| `GenerateApiReferenceDocumentationOnBuild` | `false`                  | Set the to `true` to automatically generate API documentation when the project is built.  |
+| `MdDocsMarkdownPreset`                     | `Default`                | Specify the "preset" to use for the generated markdown. Valid values: `Default`, `MkDocs` |
 
 **Note:** If the output directory already exists, all files in the output
 directory will be deleted.
@@ -127,13 +128,14 @@ To generate command line documentation for a project, run
 dotnet msbuild <PROJECT> /t:GenerateCommandLineDocumentation
 ```
 
-By default, documentation will be saved to `>$(OutputPath)docs/commandline/`.
-The output path can be customized by setting the MSBuild property
-`CommandLineDocumentationOutputPath`.
+The behaviour of the target can be customized by setting the following
+MSBuild properties:
 
-To automatically generate command line documentation when the project is built,
-set the property `GenerateCommandLineDocumentationOnBuild` to `true`
-(default: `false`).
+| Property Name                             | Default Value                    | Description                                                                                   |
+|-------------------------------------------|----------------------------------|-----------------------------------------------------------------------------------------------|
+| `CommandLineDocumentationOutputPath`      | `$(OutputPath)docs/commandline/` | The directory to save the generated documetation to.                                          |
+| `GenerateCommandLineDocumentationOnBuild` | `false`                          | Set to `true` to automatically generate command line documentation when the project is built. |
+| `MdDocsMarkdownPreset`                    | `Default`                        | Specify the "preset" to use for the generated markdown. Valid values: `Default`, `MkDocs`     |
 
 **Note:** If the output directory already exists, all files in the output
 directory will be deleted.

diff --git a/docs/commandline/commands/apireference.md b/docs/commandline/commands/apireference.md
@@ -8,17 +8,19 @@ Generate API reference documentation for a .NET assembly.
 
 ```
 mddocs apireference --assembly|-a <VALUE>
+                    [--markdown-preset <VALUE>]
                     --outdir|-o <VALUE>
                     [--verbose|-v <VALUE>]
 ```
 
 ## Parameters
 
-| Name                            | Short Name               | Required | Description                                                                                                                                     |
-| ------------------------------- | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| [assembly](#assembly-parameter) | [a](#assembly-parameter) | Yes      | Path of the assembly to generate documentation for.                                                                                             |
-| [outdir](#outdir-parameter)     | [o](#outdir-parameter)   | Yes      | Path of the directory to write the documentation to. If the output directory already exists, all files in the output directory will be deleted. |
-| [verbose](#verbose-parameter)   | [v](#verbose-parameter)  | No       | Show more detailed log output.                                                                                                                  |
+| Name                                          | Short Name               | Required | Description                                                                                                                                     |
+| --------------------------------------------- | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| [assembly](#assembly-parameter)               | [a](#assembly-parameter) | Yes      | Path of the assembly to generate documentation for.                                                                                             |
+| [markdown\-preset](#markdownpreset-parameter) |                          | No       | Specifies the preset to use for generating Markdown files.                                                                                      |
+| [outdir](#outdir-parameter)                   | [o](#outdir-parameter)   | Yes      | Path of the directory to write the documentation to. If the output directory already exists, all files in the output directory will be deleted. |
+| [verbose](#verbose-parameter)                 | [v](#verbose-parameter)  | No       | Show more detailed log output.                                                                                                                  |
 
 ### `assembly` Parameter
 
@@ -34,6 +36,20 @@ Path of the assembly to generate documentation for.
 
 ___
 
+### `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:   | 0                   |
+
+___
+
 ### `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.

diff --git a/docs/commandline/commands/commandlinehelp.md b/docs/commandline/commands/commandlinehelp.md
@@ -8,19 +8,21 @@ Generate command line help for .NET console application implemented using the 'C
 
 ```
 mddocs commandlinehelp --assembly|-a <VALUE>
+                       [--markdown-preset <VALUE>]
                        [--no-version <VALUE>]
                        --outdir|-o <VALUE>
                        [--verbose|-v <VALUE>]
 ```
 
 ## Parameters
 
-| Name                                | Short Name               | Required | Description                                                                                                                                     |
-| ----------------------------------- | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| [assembly](#assembly-parameter)     | [a](#assembly-parameter) | Yes      | Path of the command line application assembly to generate documentation for.                                                                    |
-| [no\-version](#noversion-parameter) |                          | No       | Do not include the application version in the generated documentation                                                                           |
-| [outdir](#outdir-parameter)         | [o](#outdir-parameter)   | Yes      | Path of the directory to write the documentation to. If the output directory already exists, all files in the output directory will be deleted. |
-| [verbose](#verbose-parameter)       | [v](#verbose-parameter)  | No       | Show more detailed log output.                                                                                                                  |
+| Name                                          | Short Name               | Required | Description                                                                                                                                     |
+| --------------------------------------------- | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| [assembly](#assembly-parameter)               | [a](#assembly-parameter) | Yes      | Path of the command line application assembly to generate documentation for.                                                                    |
+| [markdown\-preset](#markdownpreset-parameter) |                          | No       | Specifies the preset to use for generating Markdown files.                                                                                      |
+| [no\-version](#noversion-parameter)           |                          | No       | Do not include the application version in the generated documentation                                                                           |
+| [outdir](#outdir-parameter)                   | [o](#outdir-parameter)   | Yes      | Path of the directory to write the documentation to. If the output directory already exists, all files in the output directory will be deleted. |
+| [verbose](#verbose-parameter)                 | [v](#verbose-parameter)  | No       | Show more detailed log output.                                                                                                                  |
 
 ### `assembly` Parameter
 
@@ -36,6 +38,20 @@ Path of the command line application assembly to generate documentation for.
 
 ___
 
+### `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:   | 0                   |
+
+___
+
 ### `no-version` Parameter
 
 Do not include the application version in the generated documentation

diff --git a/src/MdDocs.Common/_Extensions/DocumentSetExtensions.cs b/src/MdDocs.Common/_Extensions/DocumentSetExtensions.cs
@@ -0,0 +1,22 @@
+using Grynwald.MarkdownGenerator;
+
+namespace Grynwald.MdDocs.Common
+{
+    public static class DocumentSetExtensions
+    {
+        public static void Save<T>(this DocumentSet<T> documentSet, string directoryPath, bool cleanOutputDirectory, MdSerializationOptions markdownOptions) where T : IDocument
+        {
+            documentSet.Save(directoryPath, cleanOutputDirectory, (document, path) =>
+            {
+                if (document is MdDocument mdDocument)
+                {
+                    mdDocument.Save(path, markdownOptions);
+                }
+                else
+                {
+                    document.Save(path);
+                }
+            });
+        }
+    }
+}
diff --git a/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.props b/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.props
@@ -18,6 +18,7 @@
   <PropertyGroup>
     <GenerateApiReferenceDocumentationOnBuild Condition="'$(GenerateApiReferenceDocumentationOnBuild)' == ''">false</GenerateApiReferenceDocumentationOnBuild>
     <GenerateCommandLineDocumentationOnBuild Condition="'$(GenerateCommandLineDocumentationOnBuild)' == ''">false</GenerateCommandLineDocumentationOnBuild>
+    <MdDocsMarkdownPreset Condition="'$(MdDocsMarkdownPreset)' == ''">Default</MdDocsMarkdownPreset>
   </PropertyGroup>
 
 </Project>
diff --git a/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.targets b/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.targets
@@ -15,7 +15,8 @@
 
     <Message Text="Saving API Reference documentation to '$(ApiReferenceDocumentationOutputPath)'" />
     <GenerateApiReferenceDocumentation Assembly="@(TargetPathWithTargetPlatformMoniker->'%(FullPath)')" 
-                                       OutputDirectory="$(ApiReferenceDocumentationOutputPath)" />
+                                       OutputDirectory="$(ApiReferenceDocumentationOutputPath)"
+                                       MarkdownPreset="$(MdDocsMarkdownPreset)" />
   </Target>
 
   <!--
@@ -47,7 +48,8 @@
 
     <Message Text="Saving command line documentation to '$(CommandLineDocumentationOutputPath)'" />
     <GenerateCommandLineDocumentation Assembly="@(TargetPathWithTargetPlatformMoniker->'%(FullPath)')"
-                                      OutputDirectory="$(CommandLineDocumentationOutputPath)" />
+                                      OutputDirectory="$(CommandLineDocumentationOutputPath)"
+                                      MarkdownPreset="$(MdDocsMarkdownPreset)" />
   </Target>
 
 

diff --git a/src/MdDocs.MSBuild/src/GenerateApiReferenceDocumentation.cs b/src/MdDocs.MSBuild/src/GenerateApiReferenceDocumentation.cs
@@ -1,6 +1,7 @@
 using System.IO;
 using Grynwald.MdDocs.ApiReference.Model;
 using Grynwald.MdDocs.ApiReference.Pages;
+using Grynwald.MdDocs.Common;
 using Microsoft.Extensions.Logging;
 
 namespace Grynwald.MdDocs.MSBuild
@@ -17,11 +18,13 @@ public override bool Execute()
                 Logger.LogInformation($"Cleaning output directory '{OutputDirectoryPath}'");
                 Directory.Delete(OutputDirectoryPath, true);
             }
-
+
+            var serializationOptions = GetSerializationOptions();
+
             using (var assemblyDocumentation = AssemblyDocumentation.FromAssemblyFile(AssemblyPath, Logger))
             {
                 var pageFactory = new PageFactory(new DefaultApiReferencePathProvider(), assemblyDocumentation, Logger);
-                pageFactory.GetPages().Save(OutputDirectoryPath, cleanOutputDirectory: true);
+                pageFactory.GetPages().Save(OutputDirectoryPath, cleanOutputDirectory: true, markdownOptions: serializationOptions);
             }
 
             return Log.HasLoggedErrors == false;

diff --git a/src/MdDocs.MSBuild/src/GenerateCommandLineDocumentation.cs b/src/MdDocs.MSBuild/src/GenerateCommandLineDocumentation.cs
@@ -1,21 +1,25 @@
 using Grynwald.MdDocs.CommandLineHelp.Model;
 using Grynwald.MdDocs.CommandLineHelp.Pages;
+using Grynwald.MdDocs.Common;
 
 namespace Grynwald.MdDocs.MSBuild
 {
     public sealed class GenerateCommandLineDocumentation : TaskBase, ICommandLinePageOptions
     {
         public bool IncludeVersion { get; set; } = true;
 
+
         public override bool Execute()
         {
             if (!ValidateParameters())
                 return false;
 
+            var serializationOptions = GetSerializationOptions();
+
             using (var model = ApplicationDocumentation.FromAssemblyFile(AssemblyPath, Logger))
             {
                 var pageFactory = new CommandLinePageFactory(model, this, new DefaultCommandLineHelpPathProvider(), Logger);
-                pageFactory.GetPages().Save(OutputDirectoryPath, cleanOutputDirectory: true); 
+                pageFactory.GetPages().Save(OutputDirectoryPath, cleanOutputDirectory: true, markdownOptions: serializationOptions);
             }
 
             return Log.HasLoggedErrors == false;

diff --git a/src/MdDocs.MSBuild/src/TaskBase.cs b/src/MdDocs.MSBuild/src/TaskBase.cs
@@ -1,5 +1,8 @@
-using Microsoft.Build.Framework;
+using System;
+using Grynwald.MarkdownGenerator;
+using Microsoft.Build.Framework;
 using Microsoft.Build.Utilities;
+using Microsoft.Extensions.Logging;
 using ILogger = Microsoft.Extensions.Logging.ILogger;
 
 namespace Grynwald.MdDocs.MSBuild
@@ -15,6 +18,7 @@ public abstract class TaskBase : Task
         [Required]
         public ITaskItem OutputDirectory { get; set; }
 
+        public string MarkdownPreset { get; set; }
 
         protected ILogger Logger
         {
@@ -41,5 +45,25 @@ protected bool ValidateParameters()
             return Log.HasLoggedErrors == false;
         }
 
+
+        protected MdSerializationOptions GetSerializationOptions()
+        {
+            if (String.IsNullOrEmpty(MarkdownPreset))
+            {
+                return MdSerializationOptions.Presets.Default;
+            }
+
+            try
+            {
+                var preset = MdSerializationOptions.Presets.Get(MarkdownPreset);
+                Logger.LogInformation($"Using preset '{MarkdownPreset}' for generating markdown");
+                return preset;
+            }
+            catch (PresetNotFoundException)
+            {
+                Logger.LogInformation($"Preset '{MarkdownPreset}' not found. Using default serialization options");
+                return MdSerializationOptions.Presets.Default;
+            }
+        }
     }
 }
diff --git a/src/MdDocs/OptionsBase.cs b/src/MdDocs/OptionsBase.cs
@@ -2,6 +2,12 @@
 
 namespace Grynwald.MdDocs
 {
+    internal enum MarkdownPresetName
+    {
+        Default,
+        MkDocs
+    }
+
     internal abstract class OptionsBase
     {
         [Option('v', "verbose", HelpText = "Show more detailed log output.")]
@@ -12,5 +18,11 @@ internal abstract class OptionsBase
             HelpText = "Path of the directory to write the documentation to. If the output directory already exists, " +
                        "all files in the output directory will be deleted.")]
         public string OutputDirectory { get; set; }
+
+        [Option("markdown-preset",
+            Required = false,
+            Default = MarkdownPresetName.Default,
+            HelpText = "Specifies the preset to use for generating Markdown files.")]
+        public MarkdownPresetName MarkdownPreset { get; set; }
     }
 }