feat: permits to specify the placement of overwrites

[Patrick8639]

Hello,

Here is a pull request for a possibility to specify the placement of overwrite files.

• Related Proposal: merge mode specified in override file #9908
• Related Append remarks value with overwrite file instead of replace #7648

[Patrick8639]

@dotnet-policy-service agree

[filzrev]

It seems Docfx.Tests.PublicApiContractTest.TestPublicApiContract test is failed on CI.

It need to update test/docfx.Tests/Api.verified.cs file by executing test on local environment.
And including changes to PR commit.

[Patrick8639]

After synchronizing the source, I've rebuild and run all the tests on my Windows PC: the tests run successfully.

[filzrev]

I've rebuild and run all the tests on my Windows PC: the tests run successfully.

Snapshot verification tests are configured to raise error on CI environment only.

docfx/test/docfx.Tests/PublicApiContractTest.cs

Line 21 in 5a3a859

return Verify(new Target("cs", publicApi)).UseFileName("Api").AutoVerify(includeBuildServer: false);

When test is executed on local environment.
Diff is auto accepted and test is reported as succeed.

I though it need to apply following diff to test/docfx.Tests/Api.verified.cs

diff --git a/test/docfx.Tests/Api.verified.cs b/test/docfx.Tests/Api.verified.cs
index 1b01828098..a4ee469295 100644
--- a/test/docfx.Tests/Api.verified.cs
+++ b/test/docfx.Tests/Api.verified.cs
@@ -1839,6 +1839,10 @@ namespace Docfx.Common
         System.IO.Stream Create(Docfx.Common.RelativePath file);
         Docfx.Common.IFileReader CreateReader();
     }
+    public interface IItemWithMetadata
+    {
+        System.Collections.Generic.Dictionary<string, object> Metadata { get; }
+    }
     public interface ILogItem
     {
         string Code { get; }
@@ -2820,7 +2824,7 @@ namespace Docfx.DataContracts.ManagedReference
         [YamlDotNet.Serialization.YamlMember(Alias="type")]
         public string Type { get; set; }
     }
-    public class ItemViewModel : Docfx.DataContracts.Common.IOverwriteDocumentViewModel
+    public class ItemViewModel : Docfx.Common.IItemWithMetadata, Docfx.DataContracts.Common.IOverwriteDocumentViewModel
     {
         public ItemViewModel() { }
         [Newtonsoft.Json.JsonProperty("additionalNotes")]

[yufeih]

Thank you @Patrick8639 !

[filzrev]

After latest main branch is merged. CS0656 errors are occurred on CI build.

It seems to be caused by PolySharp source generator is failed with following error.

POLYSP0003: Unsupported C# language version

And related issue found at PolySharp repository. Sergio0694/PolySharp#50

---

For temporary workaround.
It can be fixed by excluding Docfx.Common project from PolySharp target.

By changing this line to

<ItemGroup Condition="'$(ProjectName)' != 'Docfx.Common'">

[Patrick8639]

After latest main branch is merged. CS0656 errors are occurred on CI build.

It seems to be caused by PolySharp source generator is failed with following error.

POLYSP0003: Unsupported C# language version
For temporary workaround. It can be fixed by excluding Docfx.Common project from PolySharp target.

By changing this line to

<ItemGroup Condition="'$(ProjectName)' != 'Docfx.Common'">

Done, and it compiles now!

[codecov]

Codecov Report

Attention: Patch coverage is 12.50000% with 21 lines in your changes are missing coverage. Please review.

Project coverage is 78.84%. Comparing base (fe673ec) to head (9ff1f69).
Report is 183 commits behind head on main.

Files	Patch %	Lines
...cfx.Common/EntityMergers/ReflectionEntityMerger.cs	12.50%	18 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9937      +/-   ##
==========================================
+ Coverage   74.31%   78.84%   +4.52%     
==========================================
  Files         536      540       +4     
  Lines       23189    23457     +268     
  Branches     4056     4064       +8     
==========================================
+ Hits        17234    18494    +1260     
+ Misses       4853     3822    -1031     
- Partials     1102     1141      +39     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Patrick8639]

@yufeih
Therically the documentation should be updated to reflect the change: https://github.com/dotnet/docfx/blob/main/docs/tutorial/intro_overwrite_files.md
But my English is not very good, so how can we do it?

[yufeih]

@yufeih Therically the documentation should be updated to reflect the change: https://github.com/dotnet/docfx/blob/main/docs/tutorial/intro_overwrite_files.md But my English is not very good, so how can we do it?

https://chatgpt.com is your friend for beautiful English, or otherwise let me know if you need my assistance in updating the docs.