problem understanding the new build model

[tvogel-nid]

I'm very sorry for even asking this question but I just don't understand the new way to use Microsoft.DocAsCode.App instaed of docfx.console.
We have build machines that don't have docfx installed as tool, so till now I used docfx as nuget in the following way:

<ItemGroup>
   <PackageReference Include="docfx.console" Version="2.59.4">
     <PrivateAssets>all</PrivateAssets>
     <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
   </PackageReference>
 </ItemGroup>

just changing this to

<ItemGroup>
  <PackageReference Include="Microsoft.DocAsCode.App" Version="2.61.0" />
  <PackageReference Include="Microsoft.DocAsCode.Build.MemberLevelManagedReference" Version="2.61.0" />
</ItemGroup>

is obviously not sufficient as there is no docfx.exe in any nuget package.

I tried to understand the example mentioned but I don't get it.
I'm currently have the little Program.cs with just

using Microsoft.DocAsCode;

await Microsoft.DocAsCode.Docset.Build("docfx.json");

inside. It builds, but what is the next step?
Shall I call the build exe now in a post-build step?
Any help is really appreciated.

Discussed in #8313

^{Originally posted by yufeih December 25, 2022}

What's Changed

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

• 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.

---

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

[KalleOlaviNiemitalo]

When I ported our document projects to DocFX 2.60, I added to each repository a .config/dotnet-tools.json file that references the docfx .NET tool, and added build steps that execute dotnet tool restore and dotnet tool run docfx. This way, it installs DocFX as a local tool and should not interfere with other projects using other versions of DocFX in parallel. To keep the builds reproducible, I don't want them to automatically start using new versions of DocFX as they are released.

If I had needed custom extensions, then I'd have used Microsoft.DocAsCode.App instead of the docfx .NET tool package.

[tvogel-nid]

thanks a lot for the insight, I got it working, so I just would like to hear whether this is the expected approach as it would add changes to our company mono-repo, so changes there have to be well documented and justified.

[lanthonyneville]

Hi @KalleOlaviNiemitalo and @tvogel-nid .... I am also stuck with building a DocFx project via AzureDevops, having updated from DocFx 2.59.0 (using the console NuGet) to 2.63.1.

I tried to follow KalleOlaviNiemitalo's approach, and added the 2 build steps, plus the dotnet-tools.json manifest file to the source. However the dotnet tool restore step fails saying it can't find the manifest file. I have tried it in a .config subfolder, and in the root, but same failure. Here is the exact output of the step:

##[section]Starting: dotnet tool restore
==============================================================================
Task         : .NET Core
Description  : Build, test, package, or publish a dotnet application, or run a custom dotnet command
Version      : 2.153.3
Author       : Microsoft Corporation
Help         : https://docs.microsoft.com/azure/devops/pipelines/tasks/build/dotnet-core-cli
==============================================================================
[command]C:\WINDOWS\system32\chcp.com 65001
Active code page: 65001
[command]"C:\Program Files\dotnet\dotnet.exe" tool restore
Cannot find a manifest file.
For a list of locations searched, specify the "-d" option before the tool name.
No tools were restored.
##[section]Finishing: dotnet tool restore

The 2nd step then fails with "Cannot find a tool in the manifest file that has a command named 'docfx'" but I guess this is because it can't find the manifest file.

How do I get it to see the manifest file? Also, can you check if this is the correct format for the file? Many thanks.

{
	"version": 1,
	"isRoot": true,
	"tools": {
		"docfx": {
			"version": "2.63.1",
			"commands": [
				"docfx"
			]
		}
	}
}

[lanthonyneville]

I should say that I can build the site locally just fine, using: dotnet tool run docfx

Also, if I change the 1st step to run dotnet tool update -g docfx, it works OK with this output:

[command]"C:\Program Files\dotnet\dotnet.exe" tool update -g docfx
You can invoke the tool using the following command: docfx
Tool 'docfx' (version '2.63.1') was successfully installed.

[KalleOlaviNiemitalo]

I cannot really help with Azure DevOps.

[lanthonyneville]

I found the answer: in the AzureDevops build pipeline, in both steps above, it is necessary to set the Working Directory field (look under Advanced) to the root folder of your DocFx project.

[moonymachine]

I am also totally at a loss for how to use DocFx as a NuGet package. The instructions here, https://dotnet.github.io/docfx/index.html#use-the-nuget-library, are just not something I understand.

You can also use docfx as a NuGet library:
<PackageReference Include="Microsoft.DocAsCode.App" Version="2.60.0" />
Then build a docset using:
await Microsoft.DocAsCode.Docset.Build("docfx.json");

Which file(s) should that package reference be added to? I have a class library with three separate projects, compiling to three dlls, under one solution. I'm very much an amateur with MSBuild files, and just telling me to add a package reference is just not enough. I need a little more hand holding.

Where is that line of code supposed to live? When and how is it executed?

[moonymachine]

Based on this answer to another question, #8415 (comment), I am thinking that I should create a separate solution and project to produce an executable that runs Docset.Build. That project should include the DocFx NuGet package. That is essentially where my head was at, but very unsure of myself. A lot of this that might seem second nature to some feels pretty foreign to someone such as myself who has been working pretty exclusively in Unity3D for most of my career.

[lanthonyneville]

@moonymachine after struggling with this myself, I wrote up how I did this here: #8605