DefaultDocumentation 0.8.0 breaking changes

[Doraku]

So I am going through a major refactoring of this project, the goal is to facilitate unit testing and extension of the supported xml elements and section of the generated documentation.
DefaultDocumentation.Common will be split in three parts:

• DefaultDocumentation.Api: this project will be its own nuget package and contains all model base types and settings for documentation generation. In the futur people should be able to create their own extensions to be added to the generation logic using this package. Notable base types are:
  • ElementWriter: base type to add logic to generate a specific xml element
  • SectionWriter: base type to add whatever you want in the generated documentation for each page
• DefaultDocumentation.Markdown: this project will contains the specific implementations of all supported ElementWriter and SectionWriter to generate the current markdown documentation. As stated the library should be properly unit tested!
• DefaultDocumentation.Common: will keep what is left, mainly the logic to create the DocItems from your assembly and the documentation page generation, being the common path between msbuild task and dotnet tool execution.

I hope to be done with this pretty soon and it should greatly open up what is possible to do with DefaultDocumentation!

[pointnet]

Hello @Doraku ,

I was playing a bit with the new FileNameFactory feature and I'm facing an issue while trying to produce folders structure.

My use case is to use the sub-page feature of Azure Devops Wikis to automate documentation generation in our ci/cd process.

The issue is coming from Path.GetFileNameWithoutExtension who just remove the xxx/ part I'm trying to add in the file name.

Here's a sample implementation

public class DirectoryFileNameFactory : AMarkdownFactory
{
    public override string Name => "Directory";

    protected override string GetMarkdownFileName(IGeneralContext context, DocItem item)
    {
        if (string.IsNullOrWhiteSpace(item.Parent?.Name ?? ""))
        {
            return item.Name;
        }

        if (item.Name == item.Parent.Name)
        {
            return item.Name;
        }

        return $"{item.Parent.Name}/{item.Name}";
    }
}

Am I missing something regarding the way I'm trying to produce folder structure or is it something you need to look into ?

Thanks for your help and dedicated work on this project :)

[pointnet]

Let me explain why IPathCleaner comes to my mind, I'm not sure it's the right way to go. Here's the use case :

In Azure Devops Wiki, you can name a page Class: AuditingContext<T>.
The resulting md file is named: Class%3A-AuditingContext%3CT%3E.md.
space is replaced by -, :<> are url encoded.

So why IPathCleaner ? If I can manage to produce the file name with IFileNameFactory, I want to be sure that _pathCleaner.Clean() won't remove any of the special characters I'm using.

[pointnet]

After reading all of this again, answer is yes, I think cleaning should be delegated to the factory,

[Doraku]

yeah I think you confused the cleaning of the output folder with the cleaning of the file names to remove invalid path chars :) I will try to make some changes for this this week end.

[Doraku]

Just made some changes to allow IFileNameFactory to returns a file path with a directory hierarchy. I intend to make a plugin as an example to showcase how to extend DefaultDocumentation for #94 that should help you achieve what you want.

[Doraku]

@pointnet You can check the sample for a working example of a custom folder IFileNameFactory.