You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The OnTopic Library has a rich collection of inline documentation in the form of XML Docs. This is currently used by Visual Studio for IntelliSense, but not much beyond that.
Ideally, this would be used to generate HTML documentation which would then be published publicly.
The current version of DocFx doesn't yet support C# 10's implicit or global using directives. To mitigate this, we'll need to operate against the compiled assemblies (*.dll), instead of the projects (*.csproj) or source code (*.cs).
This can be accomplished by setting OnTopic.All as a project dependency on the DocFx project, and then adding something like the following to the docfx.json configuration:
For integrated hosting of DocFx with Visual Studio, we can create an empty ASP.NET Core 6 project, and then setup the WebApplication to support loading default, static documents from the _site folder:
By default, references to the .NET Core Base Class Library (BCL) won't be cross-referenced back to docs.microsoft.com. Per the DocFx documentation, however, this can easily be mitigated by cross-referencing Microsoft's xref service in the docfx.json file:
Instead of making this part of the OnTopic Library repository, it might make more sense to establish this as a separate repository. This would ensure that:
It could consolidate documentation from OnTopic Library, OnTopic Editor, and the Data Transfer Service, and
Make it easier to update the conceptual documentation independent of the release schedule.
Activity
JeremyCaney commentedon Jan 4, 2022
The current version of DocFx doesn't yet support C# 10's implicit or global using directives. To mitigate this, we'll need to operate against the compiled assemblies (
*.dll), instead of the projects (*.csproj) or source code (*.cs).This can be accomplished by setting
OnTopic.Allas a project dependency on the DocFx project, and then adding something like the following to thedocfx.jsonconfiguration:{ "metadata": [{ "src": [{ "files": [ "OnTopic.All/bin/Debug/netcoreapp3.1/**.dll" ] }] }] }JeremyCaney commentedon Jan 4, 2022
For integrated hosting of DocFx with Visual Studio, we can create an empty ASP.NET Core 6 project, and then setup the
WebApplicationto support loading default, static documents from the_sitefolder:This way, we can run the DocFx site directly using the IDE's integration with either IIS Express or Kestrel.
JeremyCaney commentedon Jan 4, 2022
By default, references to the .NET Core Base Class Library (BCL) won't be cross-referenced back to
docs.microsoft.com. Per the DocFx documentation, however, this can easily be mitigated by cross-referencing Microsoft'sxrefservice in thedocfx.jsonfile:{ "build": { "xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ] ... } }JeremyCaney commentedon Jan 6, 2022
Instead of making this part of the OnTopic Library repository, it might make more sense to establish this as a separate repository. This would ensure that:
This can be done by sourcing the XML documentation from the NuGet files.
Fixed circular reference
Fixed errant usage of `<code />` in favor of `<c />`
Merge branch 'maintenance/XMLDoc-fixes' into develop