Use MSBUILD to configure DocFX / Better MSBUILD integration

[ChristophLindemann]

It would be nice to integrate DocFX better into the MSBUILD ecosystem.

That would make align DocFX with .NET Core, and make it easier to configure DocFX in big solutions, use dynamic build metadata, extend DocFX via nuget packages...

• use msbuild properties to configure docfx properties, like docfx.json->build.dest, docfx.metadata.json
• use msbuild item groups to configure templates, preprocessors, content, resources...
  • use for referencing projects for which to generate API documentation
  • use for extending DocFX with templates, preprocessors...
  • use for referencing projects for which to generate API documentation
• create DocFX project type. Create msbuild SDK
• use msbuild targets to configure the docfx build/tooling pipeline, which would also make it easier to extend phases.
• Support the "standard" build log message format, so that warnings and errors are displayed correctly in IDE, and goto works
• Support building multiple output formats

[yufeih]

To support non .NET languages (#157) like python, golang, typescript, docfx should not be tied to msbuild. It can be a separate project on top optimized for C# workflow.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[stale[bot]]

Closing this issue after a prolonged period of inactivity. If you still think this issue is relevant, please feel free to ping a maintainer or leave a comment.

[open-collar]

I think it would be very useful to have docfx supported as a first class citizen in the dotnet ecosystem. In particular making the generation and publishing of documentation alongside libraries would be a very healthy thing to encourage.

[KalleOlaviNiemitalo]

We have a few documentation repositories that are built in a continuous integration system. Currently, these rely on DocFX binaries automatically installed from the CI master server. Although there is no .NET API documentation in these repositories, I've been thinking about migrating their build systems towards MSBuild (specifically dotnet msbuild, for licensing and portability) and referring to a DocFx package from NuGet (DocFx.Console looks easiest).

Unfortunately, I found that PackageReference cannot be easily made to work in a hand-crafted MSBuild project that does not intend to build any managed code and thus does not target any framework. I think it will be easier to have a C# project that builds a DLL even though it has no C# source files.

edit 2020-08-01: Microsoft.Build.NoTargets can be used instead of a fake C# project, but PackageReference still requires a TargetFramework (https://github.com/microsoft/MSBuildSdks/issues/100).

If DocFx were also packaged as an SDK for MSBuild (also microsoft/msbuild#2803), then it might be easier to use in this way.

[soroshsabz]

ITNOA

Any plan for implementing this cool feature?