Version 2.60.0-preview.2

[yufeih]

What's Changed

Addresses all known limitations in v2.60.0-preview.1:

• .NET Core: Support generating APIs from source code, csproj, DLLs without installing .NET Framework.
• Cross platform: Support Windows, Linux and MacOS
• New Extensibility Model: docfx.console and plugins are replaced with a new compile time extensibility model. To consume docfx as a library or use docfx extensions, add reference to the Microsoft.DocAsCode.App package. See samples/extensions folder on a sample using the memberpage plugin.

🎉 New Features

• feat: New extensibility model based on libraries by @yufeih in feat: New extensibility model based on libraries #8306
• feat: publish template assets as NuGet contentFiles by @yufeih in feat: publish template assets as NuGet contentFiles #8307
• feat: drop compilation dependency on .NET Framework by @yufeih in feat: drop compilation dependency on .NET Framework #8309
• feat: Support MacOS by @yufeih in feat: Support MacOS #8310
• feat: Support Ubuntu by @yufeih in feat: Support Ubuntu #8311

Full Changelog: v2.60.0-preview.1...v2.60.0-preview.2

---

This discussion was created from the release Version 2.60.0-preview.2.

[paulushub]

@yufeih Thanks for this great work and effort. Any reason the Microsoft.DocAsCode.MarkdownLite assembly is still maintained?

[yufeih]

@yufeih Thanks for this great work and effort. Any reason the Microsoft.DocAsCode.MarkdownLite assembly is still maintained?

No there is no plan to maintain it further along with some other features, but we'd like to ship a .NET core version first with max compatibility as long as there is no blocker in moving to .NET core. Once 2.60.0 ships, the next thing ahead is deprecation of these features.

[paulushub]

Thanks for the reply.

As you are working on a new plugin framework, can you consider exposing the filter interface to plugins?

[yufeih]

Definitely. Thanks for bringing up the request!

[paulushub]

Again, thanks for your commitment to this project.

This is off-topic:
You have mentioned the need to use ILSpy to resolve references, and I do understand why this special need.
When I created Sandcastle library, Cecil sufficiently resolved the assembly dependencies. In fact, if I remember well,
Cecil has a callback system for resolving the references.
Please can you expand further on this need?

[yufeih]

Cecil is a great library and is used by mdoc for producing .NET API docs internally by Microsoft for https://learn.microsoft.com, it solves the problem of reflecting .NET assemblies and resolving dependencies, but does not produce C# signatures out of assemblies. As C# introduces new syntax that impacts declaration (nullable types, records, ref struct, function pointers..), we still need work to decompile metadata representation into proper C# signatures. This job is already nicely done by ILSpy: a C# decompiler, so using ILSpy can reduce the maintenance effort in keeping up with C# evolution. In fact, ILSpy internally uses Cecil (or a forked version of Cecil).

[paulushub]

Thanks, probably just the decompiler
https://www.nuget.org/packages/ICSharpCode.Decompiler/8.0.0.7246-preview3

[yufeih]

Yep, I did a prototype here a while back.

[paulushub]

Cool, ILSpy is grown bigger but still does not produce VB.NET and F# - the down side.

[KalleOlaviNiemitalo]

A success story.

I have a continuous integration system building and deploying several documentation repos. Each repo has a handcrafted MSBuild project with a PackageReference to DocFX.Console. These projects don't use the props and targets in the package; rather, they locate docfx.exe and use the Exec task to run that with the correct parameters. docfx metadata is not used, as these docsets are not for managed APIs. (Some of these MSBuild projects also build C# code for generating Markdown.)

I was able to port one of these repos to the docfx .NET tool package quite easily, although it required a new CI step for dotnet tool restore. Now I'll just wait for a non-preview DocFX release before I merge this change and do the same to the other repositories.

[SeanKilleen]

Just wanted to say thank you for this! We've been using docfx to build https://docs.nunit.org for a while now. We created a docfx-action for GitHub actions that was based on Mono and had some complications. This greatly simplifies that, to the point of likely obsoleting it, which I'm very happy about! This was a really nice surprise to see today. Great work!