Emit a file that lists which packages don't use ///-source-of-truth #120726
Conversation
github-actions
bot
added
the
needs-area-label
There was a problem hiding this comment.
Pull Request Overview
This PR adds functionality to emit a file listing packages that don't use the ///-source-of-truth documentation standard. The change enables the docs process to identify which packages should be excluded from ingestion into dotnet-api-docs.
Key changes:
- Adds logic to identify packages without compiler-generated documentation
- Creates a text file listing these packages
- Includes the generated file in the package output
....Runtime.DotNetApiDocs.Transport/src/Microsoft.Internal.Runtime.DotNetApiDocs.Transport.proj
Outdated
Show resolved
Hide resolved
....Runtime.DotNetApiDocs.Transport/src/Microsoft.Internal.Runtime.DotNetApiDocs.Transport.proj
Show resolved
Hide resolved
| <TfmSpecificPackageFile Include="@(ReferenceAssemblyFile); | ||
| @(CompilerGeneratedXmlDocFile)" | ||
| PackagePath="ref\$(NetCoreAppCurrent)\" /> | ||
| <NoDocPackages Include="@(ProjectReferenceCopyLocalPathNonPrivate->WithoutMetadataValue('UseCompilerGeneratedDocXmlFile', 'true')->WithMetadataValue('IsPackable', 'true')->'%(PackageId)'->Distinct())" /> |
There was a problem hiding this comment.
Is this the same as searching for projects that have UseCompilerGeneratedDocXmlFile explicitly set to false?
There was a problem hiding this comment.
It's the combination of UseCompilerGeneratedDocXmlFile=false && IsPackable=true
| </ItemGroup> | ||
|
|
||
| <WriteLinesToFile Lines="@(NoDocPackages)" | ||
| File="$(OutputPath)NoDocPackages.txt" |
There was a problem hiding this comment.
In answer to @ViktorHofer question, I don't ingest packages via the transport package. Could I still read this file from the app that I run to generate the list of NuGet packages to ingest?
There was a problem hiding this comment.
Do you use this package at all today?
You could PackageDownload the package, and then use Content to copy this file from the package.
Or I could change where I place the file in the package and make it automatically copied to the output directory of the app.
Today, this transport package includes all the assemblies under ref\net10.0 which would make them automatically be referenced when the package is referenced on net10.0. I doubt this is what you want, since you probably want to treat its contents as data.
So... tell us what works best for you and we'll make it happen.
There was a problem hiding this comment.
Or I could change where I place the file in the package and make it automatically copied to the output directory of the app.
That would be great if you can.
|
@gewarren found that this is missing the packages that have framework overlap and set |
We were missing non-copy-local assemblies (EG: framework overlapping) that had packages. EG: System.Collections.Immutable System.Text.Json etc
3 participants
Here's a sample that adds a file that catalogs which libraries do not use ///-source-of-truth.
This could be used by the docs process to understand which packages to exclude from ingestion into dotnet-api-docs.
I just dumped a text file with each package on a new line. Let me know if you'd prefer some different format.