Documentation links of referenced projects (nugets)

[vougkum]

Hi, the project which I am working on the documentation has a solution with library projects with package reference. I have configured each of them as below:

<GenerateDocumentationFile>true</GenerateDocumentationFile>
    <DefaultDocumentationFolder>..\..\..\docs\wiki\xx.yy.Core</DefaultDocumentationFolder>
    <DefaultDocumentationFileNameFactory>Name</DefaultDocumentationFileNameFactory>
    <DefaultDocumentationAssemblyPageName>xx.yy.Core</DefaultDocumentationAssemblyPageName>
    <DefaultDocumentationGeneratedPages>Assembly, Interfaces, Classes</DefaultDocumentationGeneratedPages>
    <DefaultDocumentationGeneratedAccessModifiers>Public</DefaultDocumentationGeneratedAccessModifiers>
    <DefaultDocumentationIncludeUndocumentedItems>true</DefaultDocumentationIncludeUndocumentedItems>
     <DefaultDocumentationRemoveFileExtensionFromLinks>true</DefaultDocumentationRemoveFileExtensionFromLinks>
    <DefaultDocumentationLinksOutputFile>..\..\..\docs\wiki\xx.yy.Core.Links.txt</DefaultDocumentationLinksOutputFile>
     <DefaultDocumentationExternLinksFiles>..\..\..\docs\wiki\*.Links.txt</DefaultDocumentationExternLinksFiles>
     <DefaultDocumentationLinksBaseUrl>https://dev.azure.com/..Wiki?pagePath=/xx.yy.Core/</DefaultDocumentationLinksBaseUrl>

But in the generated documentation the links to the referenced library are the default ones (https://docs.microsoft.com/en-us/dotnet/api/..) and not point to the link in azure (where my wiki is). When I change the solution to project reference instead of package reference the links are generated correctly.
So I am guessing that package reference is not supported or am I missing something in the configuration?
I tried to use the which generates a second link (with the correct url) but it also generates a link which points to docs.microsoft.com.
For example in code: I get two links zz(docs.microsoft.com) zz (dev.azure.com)
Can you please advice on this?

The tool is great, the documentation generation on build is a great feature and the fact that it generates also markdown files
makes it perfect to publish it as a dev azure wiki.

Many thanks

[Doraku]

hello, hum that's weird can you confirm that the xx.yy.Core.Links.txt is correctly produced? You can look for ExternLinksFiles: in the build logs to see if it correctly found all your links file.
Can you add <DefaultDocumentationLogLevel>Debug</DefaultDocumentationLogLevel> to your csproj properties and look into the build logs for one of the id that you expect from the link files?

[vougkum]

No it is adding DocItem "DefaultDocumentation.Models.Types.InterfaceDocItem instead:
1>2022-03-15 16:31:15.9547|DEBUG|DefaultDocumentation|adding DocItem "DefaultDocumentation.Models.Types.InterfaceDocItem" with id "T:Platform.Globalization.ITimezoneService"
1>2022-03-15 16:31:16.3298|DEBUG|DefaultDocumentation|Writing DocItem "DefaultDocumentation.Models.Types.InterfaceDocItem" with id "T:Platform.Globalization.ITimezoneService"

[Doraku]

wait is that happening in the Platform.Core project or Platform.Data/Platform.DataTransfert?

[vougkum]

this is on Platform.Core build. sorry
when I build Platform.Data I see
1>2022-03-15 17:10:16.7306|DEBUG|DefaultDocumentation|adding DocItem "DefaultDocumentation.Models.ExternDocItem" with id "T:Platform.Globalization.ITimezoneService"

[Doraku]

Rah yes ok, I remember! I actually fixed this bug last week >_> Any link you would have in your documentation with <see cref="..."> to external type would work but the link generated from type introspection (like here the type of a parameter) would generate a bogus id and it could not find the ExternDocItem, thus falling back to the default dotnetapi link.
(eb8dbcb#diff-64f8e7a0ef27d88ca3795c2aec106fdb5cc90f6859ba318336b1f4e3e227de06R164 if you are curious)
The next version (with this fix and numerous new features) should be coming soon, I have written half of the new readme yesterday and still need to finish it. So hopefully by the end of the week it should be there :)

[vougkum]

many thanks!!looking forward to it!

[Doraku]

cleaning up old issues/discussion to keep relevant stuff, feel free to reopen if needed