search

Doraku / DefaultDocumentation

Create a simple markdown documentation from the Visual Studio xml one.
MIT No Attribution
157 stars 26 forks source link

Allow setting assembly URLs #68

Closed IdkGoodName closed 3 years ago

IdkGoodName commented 3 years ago

Allow us to set documentation URLs for assemblies. My project is split into multiple assemblies and generated code from parent assembly assumes that types from child assembly are from MS.

Doraku commented 3 years ago

This should be handled by using the external links feature. If you also use DefaultDocumentation on your child assembly, you can make it generate the link file automatically and then reference it in the parent assembly with a <DefaultDocumentationExternLinksFiles> property.

IdkGoodName commented 3 years ago

Thanks for the solution. Although one problem is that it seems to throw an exception whenever I use DefaultDocumentationExternLinksFiles tag with anything inside it:

/.../.nuget/packages/defaultdocumentation/0.7.5/build/DefaultDocumentation.targets(34,5): error MSB4801: The task factory "CodeTaskFactory" is not supported on the .NET Core version of MSBuild. [/.../.../Project.csproj]
/.../.nuget/packages/defaultdocumentation/0.7.5/build/DefaultDocumentation.targets(34,5): error MSB4175: The task factory "CodeTaskFactory" could not be loaded from the assembly "/usr/share/dotnet/sdk/6.0.100-preview.7.21379.14/Microsoft.Build.Tasks.Core.dll". The task factory must return a value for the "TaskType" property. [/.../.../Project.csproj]

dotnet --info output:

.NET SDK (reflecting any global.json):
 Version:   6.0.100-preview.7.21379.14
 Commit:    22d70b47bc

Runtime Environment:
 OS Name:     artix
 OS Version:  
 OS Platform: Linux
 RID:         linux-x64
 Base Path:   /usr/share/dotnet/sdk/6.0.100-preview.7.21379.14/

Host (useful for support):
  Version: 6.0.0-preview.7.21377.19
  Commit:  91ba01788d

.NET SDKs installed:
  5.0.205 [/usr/share/dotnet/sdk]
  6.0.100-preview.7.21379.14 [/usr/share/dotnet/sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 5.0.8 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 6.0.0-preview.7.21378.6 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 5.0.8 [/usr/share/dotnet/shared/Microsoft.NETCore.App]
  Microsoft.NETCore.App 6.0.0-preview.7.21377.19 [/usr/share/dotnet/shared/Microsoft.NETCore.App]

To install additional .NET runtimes or SDKs:
  https://aka.ms/dotnet-download

My project's target framework is netstandard2.1

Default documentation settings:

<DefaultDocumentationFolder>../Documentation/Project</DefaultDocumentationFolder>
<DefaultDocumentationFileNameMode>Name</DefaultDocumentationFileNameMode>
<DefaultDocumentationAssemblyPageName>Project</DefaultDocumentationAssemblyPageName>
<DefaultDocumentationGeneratedPages>Assembly,Types,Members</DefaultDocumentationGeneratedPages>
<DefaultDocumentationGeneratedAccessModifiers>Public,ProtectedInternal,Protected</DefaultDocumentationGeneratedAccessModifiers>

<DefaultDocumentationLinksBaseUrl>(URL to reference pages)</DefaultDocumentationLinksBaseUrl>
<DefaultDocumentationExternLinksFiles>../Documentation/*.link</DefaultDocumentationExternLinksFiles>

<DefaultDocumentationRemoveFileExtensionFromLinks>true</DefaultDocumentationRemoveFileExtensionFromLinks>
Doraku commented 3 years ago

I wasn't aware that linux doesn't support CodeTaskFactory >_< https://github.com/dotnet/msbuild/issues/616 Sorry I will need to fix this part so it works for you.