Skip to content

Enable publishing XML documentation #1062

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 11, 2017
Merged

Enable publishing XML documentation #1062

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1afbf31
Publish XML documentaiton by default and enable opting out of publisi…
dasMulli Apr 3, 2017
56d9419
Renamed PublishProjectReferenceDocumentationFiles to PublishReference…
dasMulli Apr 6, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion src/Tasks/Microsoft.NET.Build.Tasks/build/Microsoft.NET.Publish.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,12 @@ Copyright (c) .NET Foundation. All rights reserved.
<ResolvedFileToPublish Include="@(ResolvedAssembliesToPublish)">
<RelativePath>%(ResolvedAssembliesToPublish.DestinationSubPath)</RelativePath>
</ResolvedFileToPublish>

<!-- Copy the xml documentation (if enabled) -->
<ResolvedFileToPublish Include="@(FinalDocFile)"
Condition="'$(PublishDocumentationFile)' == 'true'">
<RelativePath>@(FinalDocFile->'%(Filename)%(Extension)')</RelativePath>
</ResolvedFileToPublish>
</ItemGroup>

</Target>
Expand All @@ -211,7 +217,9 @@ Copyright (c) .NET Foundation. All rights reserved.
<!-- TODO perform any preprocess transforms on the files -->

<ItemGroup>
<ResolvedAssembliesToPublish Include="@(ReferenceCopyLocalPaths)" Exclude="@(ResolvedAssembliesToPublish)">
<ResolvedAssembliesToPublish Include="@(ReferenceCopyLocalPaths)"
Exclude="@(ResolvedAssembliesToPublish)"
Condition="'$(PublishReferencesDocumentationFiles)' == 'true' or '%(Extension)' != '.xml'">
<DestinationSubPath>%(ReferenceCopyLocalPaths.DestinationSubDirectory)%(Filename)%(Extension)</DestinationSubPath>
</ResolvedAssembliesToPublish>
</ItemGroup>
Expand Down
6 changes: 6 additions & 0 deletions src/Tasks/Microsoft.NET.Build.Tasks/build/Microsoft.NET.Sdk.BeforeCommon.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,12 @@ Copyright (c) .NET Foundation. All rights reserved.
<DocumentationFile />
</PropertyGroup>

<PropertyGroup>
<PublishDocumentationFiles Condition="'$(PublishDocumentationFiles)' == ''">true</PublishDocumentationFiles>
<PublishDocumentationFile Condition="'$(PublishDocumentationFile)' == '' and '$(PublishDocumentationFiles)' == 'true'">true</PublishDocumentationFile>
<PublishReferencesDocumentationFiles Condition="'$(PublishReferencesDocumentationFiles)' == '' and '$(PublishDocumentationFiles)' == 'true'">true</PublishReferencesDocumentationFiles>
</PropertyGroup>

<!-- Add a project capability so that the project properties in the IDE can show the option to generate an XML documentation file without specifying the filename -->
<ItemGroup>
<ProjectCapability Include="GenerateDocumentationFile" />
Expand Down
94 changes: 94 additions & 0 deletions test/Microsoft.NET.Publish.Tests/GivenThatWeWantToPublishAProjectWithDependencies.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@
using System.Runtime.InteropServices;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.Collections.Generic;
using Microsoft.NET.TestFramework.ProjectConstruction;

namespace Microsoft.NET.Publish.Tests
{
Expand Down Expand Up @@ -195,6 +197,98 @@ public void It_publishes_projects_with_filter_and_rid()

//TODO: Enable testing the run once dotnet host has the notion of looking up shared packages
}


[Theory]
[InlineData("GenerateDocumentationFile=true", true, true)]
[InlineData("GenerateDocumentationFile=true;PublishDocumentationFile=false", false, true)]
[InlineData("GenerateDocumentationFile=true;PublishReferencesDocumentationFiles=false", true, false)]
[InlineData("GenerateDocumentationFile=true;PublishDocumentationFiles=false", false, false)]
public void It_publishes_documentation_files(string properties, bool expectAppDocPublished, bool expectLibProjectDocPublished)
{
var kitchenSinkAsset = _testAssetsManager
.CopyTestAsset("KitchenSink", identifier: $"{expectAppDocPublished}_{expectLibProjectDocPublished}")
.WithSource();
kitchenSinkAsset.Restore("TestApp");

var publishCommand = new PublishCommand(Stage0MSBuild, Path.Combine(kitchenSinkAsset.TestRoot, "TestApp"));
var publishResult = publishCommand.Execute("/p:" + properties);

publishResult.Should().Pass();

var publishDirectory = publishCommand.GetOutputDirectory();

if (expectAppDocPublished)
{
publishDirectory.Should().HaveFile("TestApp.xml");
}
else
{
publishDirectory.Should().NotHaveFile("TestApp.xml");
}

if (expectLibProjectDocPublished)
{
publishDirectory.Should().HaveFile("TestLibrary.xml");
}
else
{
publishDirectory.Should().NotHaveFile("TestLibrary.xml");
}
}

[Theory]
[InlineData("PublishReferencesDocumentationFiles=false", false)]
[InlineData("PublishReferencesDocumentationFiles=true", true)]
public void It_publishes_referenced_assembly_documentation(string property, bool expectAssemblyDocumentationFilePublished)
{
var identifier = property.Replace("=", "");

var libProject = new TestProject
{
Name = "NetStdLib",
IsSdkProject = true,
TargetFrameworks = "netstandard1.0"
};

var libAsset = _testAssetsManager.CreateTestProject(libProject, identifier: identifier)
.Restore("NetStdLib");

var libPublishCommand = new PublishCommand(Stage0MSBuild, Path.Combine(libAsset.TestRoot, "NetStdLib"));
var libPublishResult = libPublishCommand.Execute("/t:Publish", "/p:GenerateDocumentationFile=true");
libPublishResult.Should().Pass();
var publishedLibPath = Path.Combine(libPublishCommand.GetOutputDirectory("netstandard1.0").FullName, "NetStdLib.dll");

var appProject = new TestProject
{
Name = "TestApp",
IsSdkProject = true,
IsExe = true,
TargetFrameworks = "netcoreapp2.0",
RuntimeFrameworkVersion = RepoInfo.NetCoreApp20Version,
References = { publishedLibPath }
};

var appAsset = _testAssetsManager.CreateTestProject(appProject, identifier: identifier);
var appSourcePath = Path.Combine(appAsset.TestRoot, "TestApp");

new RestoreCommand(Stage0MSBuild, appSourcePath).Execute().Should().Pass();
var appPublishCommand = new PublishCommand(Stage0MSBuild, appSourcePath);
var appPublishResult = appPublishCommand.Execute("/p:" + property);
appPublishResult.Should().Pass();

var appPublishDirectory = appPublishCommand.GetOutputDirectory("netcoreapp2.0");

if (expectAssemblyDocumentationFilePublished)
{
appPublishDirectory.Should().HaveFile("NetStdLib.xml");
}
else
{
appPublishDirectory.Should().NotHaveFile("NetStdLib.xml");
}
}

private static JObject ReadJson(string path)
{
using (JsonTextReader jsonReader = new JsonTextReader(File.OpenText(path)))
Expand Down