Releases: ap0llo/mddocs
v0.6.39
New Features
- .NET CLI tool: Allow mddocs to run on newer versions of .NET by default
- MSBuild Integration: Run MdDocs outside MSBuild process
Bug Fixes
- Remove framework assembly references from Grynwald.MdDocs.MSBuild NuGet package
- Retain blank lines from <code> blocks in the Markdown output
Breaking Changes
Details
.NET CLI tool: Allow mddocs to run on newer versions of .NET by default
Enable .NET runtime setting to allow running mddocs on newer versions of .NET if none of the supported runtimes are available.
This means - while currently, the mddocs CLI tool supports .NET 6 and .NET 7, it will use the .NET 8 or newer runtime when no version of .NET 6 or .NET 7 is installed.
- See Also: https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-core-2-1#roll-forward
- Commit:
781564e
MSBuild Integration: Run MdDocs outside MSBuild process
Breaking Change: The Grynwald.MdDocs.MSBuild package now requires the .NET 6 (or later) runtime to be installed, even when running in "Full Version" MSBuild or Visual Studio
In the MSBuild integration, replace the MdDocs MSBuild tasks that run MdDocs inside the MSBuild process with targets that run the MdDocs CLI in a separate process.
This way, MdDocs needs to only run on .NET 6 / .NET 7 and no longer has to consider compatibility with .NET Framework.
Also, this should resolve any dependency conflicts between MdDocs and MSBuild.
The MSBuild integration continues to work in both the "Core" (.NET SDK) and "Desktop" (Visual Studio) versions of MSBuild as long as a compatible .NET runtime is installed.
Remove framework assembly references from Grynwald.MdDocs.MSBuild NuGet package
Remove redundant framework assembly references since the Grynwald.MdDocs.MSBuild package is a build tools package which does not require references to .NET Framework assemblies to be added to consuming projects.
Retain blank lines from <code> blocks in the Markdown output
Update dependency Grynwald.MarkdownGenerator to version 3.0.106 which includes a fix for serialization of Markdown code blocks (all blank lines from code blocks used to be removed from the output).
v0.5.180
New Features
- API Reference: Add multi-assembly support
- Command Line Help: Order parameters in the "Usage" section
- Add .NET 6 support
- Add .NET 7 Support
- Remove support for older versions of .NET and Visual Studio
Bug Fixes
- Command Line Help: Disable syntax-highlighting for a command's "Usage" CommandUsageSection
- Make sorting in output consistent across different frameworks
- API Reference: Fix rendering of default values of value type and decimal parameters
Breaking Changes
- The mddocs:apireference:assemblyPath setting was renamed to mddocs:apireference:assemblyPaths and its type was changed from a string to an array of strings
- The '--assembly' command line parameter of the apireference command has been renamed to '--assemblies'
- The MdDocs CLI tool now requires at least .NET 6
- The MdDocs.MSBuild package is now requires at least the .NET 6 SDK (when running on MSBuild Core) or Visual Studio 2022 (when running on "Desktop MSBuild")
Details
API Reference: Add multi-assembly support
- Breaking Change: The mddocs:apireference:assemblyPath setting was renamed to mddocs:apireference:assemblyPaths and its type was changed from a string to an array of strings
- Breaking Change: The '--assembly' command line parameter of the apireference command has been renamed to '--assemblies'
Add support for rendering API reference documentation for multiple assemblies.
When multiple assemblies are specified, documentation is generated for all types from all assemblies.
The file layout of the output is unchanged and is based on a symbol's name and namespace.
Specifying multiple input assemblies is supported in the MdDocs command line tool but not in the MdDocs MSBuild task which continues to generate documentation for the current project's output assembly.
Command Line Help: Order parameters in the "Usage" section
In a command's "Usage" section, order the parameters.
Positional parameters are ordered by their position, followed by named parameters (required parameters first, then ordered by name) and switch parameters (ordered by name)
- Commit:
e51f605
Add .NET 6 support
Add support for running MdDocs on .NET 6
Add .NET 7 Support
Add support for running the MdDocs .NET CLI tool on .NET 7 and add test to ensure MdDocs.MSBuild works on the .NET 7 SDK
Remove support for older versions of .NET and Visual Studio
- Breaking Change: The MdDocs CLI tool now requires at least .NET 6
- Breaking Change: The MdDocs.MSBuild package is now requires at least the .NET 6 SDK (when running on MSBuild Core) or Visual Studio 2022 (when running on "Desktop MSBuild")
In the MdDocs CLI tool, remove support for .NET Core 3.1 and .NET 5 which have both reached their end-of-life.
For the MdDocs MSBuild package, remove support for running on the .NET Core 3.1 and .NET 5 SDKs (in the case of MSBuild Core) and versions of Visual Studio older than Visual Studio 2022 (in the case of "Desktop MSBuild")
Command Line Help: Disable syntax-highlighting for a command's "Usage" CommandUsageSection
Add Markdown info string "txt" to usage sections to prevent (wrong) syntax highlighting from being applied to it.
- Commit:
14c5ae5
Make sorting in output consistent across different frameworks
.NET 5 changed the default sorting behavior for strings causing the output of MdDocs to be different when running on net5.0 vs. running on earlier .NET Core versions or .NET Framework.
Make sorting consistent by explicitly using "Ordinal" comparisons for all sort operations.
- See Also: https://docs.microsoft.com/en-us/dotnet/standard/base-types/string-comparison-net-5-plus
- Commit:
4846d07
API Reference: Fix rendering of default values of value type and decimal parameters
Fixes rendering of value type and decimal parameters in method default values
Thanks @madelson
Contributors
Assets 4
v0.4.179
Make sorting in output consistent across different frameworks
.NET 5 changed the default sorting behavior for strings causing the output of MdDocs to be different when running on net5.0 vs. running on earlier .NET Core versions or .NET Framework.
Make sorting consistent by explicitly using "Ordinal" comparisons for all sort operations.
- See-Also: https://docs.microsoft.com/en-us/dotnet/standard/base-types/string-comparison-net-5-plus
- Commit:
0914192
v0.4.178
Fix FileNotFoundException in MSBuild tasks
Fix FileNotFoundException caused by assembly resolution errors in the MSBuild task.
Adds integration tests to verify MdDocs MSBuild tasks can run in the build for both the .NET Core SDK (2.1 and 3.1) and full/.NET Framework MSBuild.
v0.4.163
Known Issues
New Features
- Update dependencies to the latest versions
- Add configuration file support
- Include notice in output files to indicate files are auto-generated
- API Reference: Include assembly version in generated API Reference documentation
- Command Line Help: Add accepted values for commandline parameters of type bool?
- Add JSON Schema for the configuration file.
- Add support for templates
Bug Fixes
- Command Line Help: Fix incompatibility with CommandLineParser 2.8.0
- API Reference: Use correct casing for boolean literals in generated C# definitions
- Command Line Help: Fix loading of commands and parameters when the option class is a nested type
Breaking Changes
- The MSBuild integration no longer defines a default value for the output path. To set the output path, specify it either in the configuration file or set the MSBuild property ApiReferenceDocumentationOutputPath respectively CommandLineDocumentationOutputPath.
- The command line parameters 'markdown-preset' and 'no-version' have been removed. Use corresponding settings in configuration file instead.
- The MSBuild property 'MdDocsMarkdownPreset' is no longer supported. Use corresponding setting in configuration file instead.
Details
Update dependencies to the latest versions
Update dependencies to their respective latest stable version
Add configuration file support
Breaking Change: The MSBuild integration no longer defines a default value for the output path. To set the output path, specify it either in the configuration file or set the MSBuild property ApiReferenceDocumentationOutputPath respectively CommandLineDocumentationOutputPath.
Add support for specifying settings in a configuration file that can be used by both the MdDocs CLI as well as the MdDocs MSBuild targets.
The configuration system integrates both the (optional) configuration file and commandline parameters (MdDocs CLI) / MSBuild Properties (MdDocs MSBuild targets).
Include notice in output files to indicate files are auto-generated
Add a comment at the beginning of each generated markdown document to indicate the file was auto-generated by a tool.
Add setting to disable the comment to configuration.
API Reference: Include assembly version in generated API Reference documentation
By default, include the assembly version in the generated API reference documentation on pages for types and type members. Additionally, the documentation for type members will now also include the namespace and assembly name of the declaring type.
The inclusion of the assembly version can be disabled in the configuration file or using the '--no-version' command line switch of the 'apireference' command (analogous to the 'commandlinehelp' command).
Command Line Help: Add accepted values for commandline parameters of type bool?
When a commandline parameter property is of type bool?, automatically determine accepted values to be "true" and "false"
- Commit:
1d5ad35
Add JSON Schema for the configuration file.
Add a JSON Schema for the configuration file to provide auto-completion support when editing the file in editors that support JSON Schema (e.g. Visual Studio Code).
- Commit:
52d3831
Add support for templates
- Breaking Change: The command line parameters 'markdown-preset' and 'no-version' have been removed. Use corresponding settings in configuration file instead.
- Breaking Change: The MSBuild property 'MdDocsMarkdownPreset' is no longer supported. Use corresponding setting in configuration file instead.
Implement support for having different output templates. By default, the output produced will be the same as previous versions, because the existing implementation is included as the default template.
Because some options (like "Markdown Preset") are specific to the template being used, these settings have been moved to the default template's configuration section in the configuration file.
Additionally, the corresponding commandline parameters (of the .NET CLI tool version of MdDocs) and MSBuild properties (for the MSBuild-integrated version) have been removed because it would lead to confusion if some settings for one of the templates would be exposed as "top-level" parameter.
Command Line Help: Fix incompatibility with CommandLineParser 2.8.0
CommandLineParser 2.8 introduced an additional constructor parameter for VerbAttribute which cause loading command line help to fail. Adjust loading of commands to accommodate for that change.
The fix is backwards compatible and should also work with earlier versions of the CommandLineParser library.
- Commit:
2e54ad9
API Reference: Use correct casing for boolean literals in generated C# definitions
In generated definitions that contain bool literals, emit the literals as "true" and "false" instead of "True" and "False".
Command Line Help: Fix loading of commands and parameters when the option class is a nested type
Load types recursively to discover all types annotated with [Verb] and/or [Option] attributes instead of just loading top-level types.
- Commit:
dad143b
v0.3.84
Changes:
- f73a053 fix(commandlinehelp): Ignore hidden commands [ #20 ]
- 4da63a5 feat(commandlinehelp): Improve handling of boolean parameters [ #7 ]
- cf1350e feat: Update MarkdownGenerator library to version 2.4.30
- 1adaa66 feat: Add support for params method parameters
- 77ca032 fix(apireference): Hide non-public attributes [ #16 ]
- 9514504 build: Enable nullable reference types
- 3ec4580 build: Retarget projects to .NET Core 3.1
- 7444151 build: Use .NET Core 3.1 SDK
- 82fe64d docs: Cleanup README by moving "Installation" and "Usage" to separate documents [Skip CI]
- 965c709 feat(apireference): Add support for nested types [ #6 ]
- 96e8ba8 fix(apireference): Improve handling of flags enum ins CSharpDefinitionFormatter
- 642a5e6 feat(apireference): Show parameter attributes in method definition
- 80b9b6a feat(apireference): Show default parameters in method definition
- a170450 feat(apireference): Add support for 'in' parameters
- 8246b41 feat(apireference): Add support for ref and out parameters [ #5 ]
- fcc06cb fix: Always use UTF-8 encoding for saving documents
- 6512381 fix: Fix execution of MSBuild-integrated docs generation
v0.2.47
v0.2.46
v0.2.45
v0.2.44
Package available on NuGet.org
Changes:
- 717af08 fix(commandlinehelp): Fix display of default value for enum parameters
- 816b902 feat: Add "preset" option to adjust output files to target renderer
- e4f9b9d feat(apireference): Support external links in element
- f386601 feat(apireference): Allow linking to external resources by adding a "href" attribute to elements
- e9dc763 feat(apireference): Add support for specifying text inside the tag
- a5b70df feat: Adjust documentation output directory layout
- 26e0edb fix(apireference): Fix incorrect handling of whitespace in XML documentation files
- b76f2f4 feat(commandlinehelp): Add option to omit version from generated documentation