Proposal: Ability to read config from file

[hairlesshobo]

So I had an idea this morning that I would like to get your input on. What if we had the ability to configure DefaultDocumentation via a config file? I am not suggesting that we replace what is currently there, but instead supplement it.

A good use case for this would be if you have a repo that has multiple child projects all inside it. If you want the configuration to be shared between all of them, wouldn't it be nice if we could reference one config file from each .csproj? This would reduce the clutter in the .csproj file as well as allowing for one place to configure DefaultDocumentation repo-wide.

I already have an idea how to implement this and would be happy to put in the work, but wanted to run it by you before I do. Let me give an overview of the implementation I had in mind...

Currently I configure DefaultDocumentation via .csproj as such:

  <PropertyGroup>
    <PackageId>MyAwesome.Project</PackageId>

    <TargetFramework>netstandard2.0</TargetFramework>

    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>

    <DefaultDocumentationFolder>../docs/api</DefaultDocumentationFolder>

    <DefaultDocumentationIgnoreLineBreak>true</DefaultDocumentationIgnoreLineBreak>
    <DefaultDocumentationIncludeUndocumentedItems>true</DefaultDocumentationIncludeUndocumentedItems>
    <DefaultDocumentationGeneratedAccessModifiers>public</DefaultDocumentationGeneratedAccessModifiers>
  </PropertyGroup>

If I want to use this same config in all my projects, I have to copy-paste it to all of them. Instead, I propose we add one more option called ConfigFile (to both the MSBuild target and the CLI version) that can load the config from json, as such:

{
  "Folder": "./docs/api", 
  "IgnoreLineBreak": true,
  "IncludeUndocumentedItems": true,
  "GeneratedAccessModifiers": [ "public" ]
}

Then, it could simply reference this config file as such:

  <PropertyGroup>
    <PackageId>MyAwesome.Project</PackageId>

    <TargetFramework>netstandard2.0</TargetFramework>

    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>

    <!-- Open to better ideas for the "standard" file name!! -->
    <DefaultDocumentationConfig>../ddocs.json</DefaultDocumentationConfig>
</PropertyGroup>

and from the CLI tool...

# again, open to better ideas for the "standard" name!
defaultdocumentation --Config ../ddocs.json

Note: I believe this should be implemented in a way that, if a configuration value is specified in both the loaded config file, and directly in the .csproj or on the cli, the config file should be "overridden" by the local value that is specified elsewhere.

Please let me know what you think! I am really excited about what you have already built in this project and I have quite a few ideas for ways i would like to contribute.

[Doraku]

Thank you for this suggestion, I was actually thinking of doing the same things for a while, we have such a system for our tools at work and it is quite handy. As the number of configuration things grows it would be quite nice to have a centralized configuration file that can be used both for msbuild task and dotnet tool.

[hairlesshobo]

Excellent! Unless you object, I'll start working on this today.

Be thinking about what you would like the "standard" name of the json file to be. I want to be sure whatever we pick doesn't overlap with all the other such root config files out there (such as project.json, package.json, etc)

A couple ideas I had:

• ddocs.json
• ddconfig.json
• DefaultDocumentation.json

Personally, I prefer the shorter names but this is your project so let me know what you think!

[Doraku]

hum I wasn't planning on searching for a default configuration file but it may be a good idea. I think it's better to keep a full explicit name so I would go with DefaultDocumentation.json, it's more verbose but also futur proof, and people can change it in the csproj anyway with DefaultDocumentationConfig.

[hairlesshobo]

I didn't meant a name to use to search for a file, I was referring to the name that we would use in documentation and examples.

I hadn't thought about auto-searching for a specific config file by name, but that is a cool idea. Many other projects already do this, so it wouldn't be unheard of to do. I can make that happen as well, if you would like. Personally, I would only need explicitly reference the config file, but some people may prefer it be more automatic.

Additionally, we could implement the "auto" config file search as an option, either by specifying something like auto to --ConfigFile, or a separate option like --AutoLoadConfig.

Let me know what you think and I am happy to implement it any way you think is best.

[Doraku]

Nlog does so for example. The idea I had in mind was only for the msbuild task, basically if the DefaultDocumentationConfig is empty, set it to DefaultDocumentation.json from the project path in the targets file, that way it will automatically try to load the config as if it was given by the user, no extra code path needed. But it means we should not throw if the file doesn't exist (maybe just a log info). For the dotnet tool you would have to give the config file explicitly, as we don't know from where the command line will be used. I feel having a magic default config in this use case is not worth it.

[hairlesshobo]

Sounds like a great way to handle it. I'll make it happen.