DefaultDocumentation 0.7.0 breaking changes

[Doraku]

Not sure if anyone is going to read this but eh, pretty big update with a complete refactoring of the markdown generation. The main goal was to centralize the template in one place, completely splitting the model from the writer, in an effort to make appear a way to handle custom page generation. It's not there yet but it's much easier to see what is going on now.
The second goal was to ease adding new configuration features if needed instead of doing some awkward manual parsing.
This opened the way to expose DefaultDocumentation as a dotnet tool package which can interest some people who wants more control on when to generate the documentation.

Breaking changes

• changed file name generation for FullName and Name FileNameMode

This is due to a pretty bad choice on my part at the beginning of DefaultDocumentation, handling space and special characters differently when generating file names. While file name will change slightly, I think it's better to have a uniform replace by a single character which can be override by configuration.

• changed tool to msbuild task to remove runtime dependencies

This should actually not be a breaking change and something better! Before there was some condition shenanigan to either use the netframework or the netcore runtime to run the tool. As it is exposed as a netstandard2.0 msbuild task it should now run almost everywhere whatever the runtime you have installed on your machine/ci.

• renamed DefaultDocumentationNestedTypeVisibility to DefaultDocumentationNestedTypeVisibilities

This is just to follow guidelines for flags enums and make more sens

• renamed DefaultDocumentationWikiLinks to DefaultDocumentationRemoveFileExtensionFromLinks

While this feature was added specifically for documentation hosted as wiki, I think its name should be more explicit, and since I am doing many breaking changes already, might as well do everything that bothers me now and be done with it

• renamed DefaultDocumentationHome to DefaultDocumentationAssemblyPageName

Again with the big refactoring came a lot of feature, like the possibility to configure which pages will be generated. It made more sens to call the main page the assembly than the home

I tried my best to check that the generated documentation is exactly the same as the one generated by the previous version, hopefully I haven't missed much but if you see something weird once the new version is available, please don't hesitate to notify me :)

New features coming

• added support for source and region attributes in code element (Add support for code examples from actual code #40 thanks to @basvanderlaken)
• added support for language attributes in code element
• added See Also section at the end of pages grouping all seealso element
• added support for see and seealso displayed text change with element value
• added dotnet tool package (Expose DefaultDocumentation as a dotnet tool #25)
• added DefaultDocumentationGeneratedPages property to set which element will have its own page (Add a setting to put all of the info about a class into a single markdown file #36)
• added cross assembly documentation linking (allow cross assembly documentation linking #7)

I will redo the readme soon to expose some of the new features. I still want to finally add attribute informations (#8) to the documentation before creating the release so not sure when it will be available. In the meantime the preview version is already available.

[kshabani]

Hi, really want to use the tool but cant seem to be able to set up the properties or as shown in the MS Buildtask docu. I am using Visual Studio 2019. Where can I add these properties ?

[Doraku]

Those should be directly added inside the csproj file, there is no ui to do so. With the new sdk csproj format this file is much more lightweight and easy to edit by hand.
Those properties can be defined in any <PropertyGroup> element of the root <Project> element:

<Project Sdk="Microsoft.NET.Sdk">
  ...
  <PropertyGroup>
    <DefaultDocumentationFolder>..\..\documentation\api</DefaultDocumentationFolder>
    <DefaultDocumentationAssemblyPageName>MyAssembly</DefaultDocumentationAssemblyPageName>
    <DefaultDocumentationFileNameMode>Name</DefaultDocumentationFileNameMode>
    <DefaultDocumentationGeneratedPages>Assembly, Types, Members</DefaultDocumentationGeneratedPages>
  </PropertyGroup>
  ...
</Project>

If you are still using the old verbose csproj format, it should be the same but you will have to open the csproj in your text editor of choice because VisualStudio do not allow to edit the csproj directly in the IDE while if you are using the new sdk format it will show you the file content in the IDE if you just select the project in the solution explorer.

[kshabani]

Doesn't seem to create .md file. Have followed everything.

[Doraku]

After some testing it seems the old csproj format does not automatically add the <GenerateDocumentationFile>true</GenerateDocumentationFile> property when setting the <DocumentationFile>. Setting it manually should make DefaultDocumentation run as expected. I think I will change the execution condition to only <DocumentationFile> since <GenerateDocumentationFile> is not always here :/

[kshabani]

Works like a charm. Really nice. Thanks a whole lot.