diff --git a/README.md b/README.md index 7b38a26a..2dd6b0ec 100644 --- a/README.md +++ b/README.md @@ -102,13 +102,14 @@ To generate API reference for a project, run dotnet msbuild /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 /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 index ed459935..badc6cd2 100644 --- 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 + [--markdown-preset ] --outdir|-o [--verbose|-v ] ``` ## 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 index 996bab4b..d5bc555c 100644 --- a/docs/commandline/commands/commandlinehelp.md +++ b/docs/commandline/commands/commandlinehelp.md @@ -8,6 +8,7 @@ Generate command line help for .NET console application implemented using the 'C ``` mddocs commandlinehelp --assembly|-a + [--markdown-preset ] [--no-version ] --outdir|-o [--verbose|-v ] @@ -15,12 +16,13 @@ mddocs commandlinehelp --assembly|-a ## 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 new file mode 100644 index 00000000..1a811c65 --- /dev/null +++ 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(this DocumentSet 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 index 78275cc0..b223030d 100644 --- a/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.props +++ b/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.props @@ -18,6 +18,7 @@ false false + Default \ No newline at end of file diff --git a/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.targets b/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.targets index 622fc24f..9f353c6a 100644 --- a/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.targets +++ b/src/MdDocs.MSBuild/build/Grynwald.MdDocs.MSBuild.targets @@ -15,7 +15,8 @@ + OutputDirectory="$(ApiReferenceDocumentationOutputPath)" + MarkdownPreset="$(MdDocsMarkdownPreset)" />