Cake.DocFx icon indicating copy to clipboard operation
Cake.DocFx copied to clipboard
verified publisher icon cake-contrib

Unable To Select docfx.json Configuration File

Open SkyeHoefling opened this issue 5 years ago • 1 comments

When using the DocFxBuild command I am unable to use the docfx.json configuration file. I have compared the output between using the docfx.exe command and the build.cake script I have built and it appears the cake script is not pulling the configuration file. It looks like it is using a default configuration.

Expected Behavior

  • The docfx.json file should be used from the root directory where the build.cake file is also located
  • When specified the docfx.json file should be used

Current Behavior

  • The standard configuration is being used instead of the config file

Possible Solution

Not sure

Steps to Reproduce (for bugs)

See reproduction project attached docfx_project.zip

Project Setup steps

I used the dotnet CLI - use the command below to restore the tools so the steps work

  1. Extract docfx_project
  2. cd docfx_project
  3. dotnet tool restore

Run standard docfx.exe without cake

Once the project is setup verify everything is working with cake

docfx

One of the first lines in the output should read

[20-07-24 05:24:04.576]Info:Config file docfx.json found, start generating metadata...

This tells me the configuration has been loaded correctly.

Run DocFx with Cake.build script

If the first test works successfully, try running the default cake script which assumes the docfx.json file is in the working directory (according to the docs)

dotnet cake

The first few statements don't mention anything about the configuration file

========================================
Build
========================================
[20-07-24 05:26:09.106]Info:6 plug-in(s) loaded.
[20-07-24 05:26:09.183]Info:No files are found with glob pattern apidoc/**.md, excluding obj/**,_site/**, under directory "D:\docfx-test\docfx_project"
[20-07-24 05:26:09.186]Info:No files are found with glob pattern images/**, excluding <none>, under directory "D:\docfx-test\docfx_project"
[20-07-24 05:26:09.215]Info:Markdown engine is markdig
[20-07-24 05:26:09.302]Info:Cannot load build info: 'build.info' not found under 'D:\docfx-test\docfx_project\obj\.cache\build'
[20-07-24 05:26:09.378]Info:[BuildCore.Build Document]Max parallelism is 8.
[20-07-24 05:26:09.968]Info:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.TocDocumentProcessor]Building 3 file(s) in TocDocumentProcessor(BuildTocDocument)...
[20-07-24 05:26:09.969]Info:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ConceptualDocumentProcessor]Building 3 file(s) in ConceptualDocumentProcessor(BuildConceptualDocument=>CountWord=>ValidateConceptualDocumentMetadata)...
[20-07-24 05:26:10.637]Info:[BuildCore.Build Document.LinkPhaseHandlerWithIncremental.Apply Templates]Applying templates to 6 model(s)...
[20-07-24 05:26:11.016]Info:[BuildCore.Build Document]XRef map exported.
[20-07-24 05:26:11.138]Info:[Postprocess]Manifest file saved to manifest.json.
[20-07-24 05:26:11.249]Info:Completed building documents in 2131.9093 milliseconds.
[20-07-24 05:26:11.252]Info:Completed in 2752.9553 milliseconds


Build succeeded.
        0 Warning(s)
        0 Error(s)

========================================
Default
========================================

Task                          Duration
--------------------------------------------------
Build                         00:00:03.4805529
--------------------------------------------------
Total:                        00:00:03.4831818

Run DocFx with Cake.build script targeting config file

I thought maybe the working directory is off and it is unable to find the config file. I added another test to specify the config file location. The output appears very similar the previous test

dotnet cake --Target=BuildWithConfig

Build Output:

========================================
BuildWithConfig
========================================
[20-07-24 05:27:59.484]Info:6 plug-in(s) loaded.
[20-07-24 05:27:59.537]Info:No files are found with glob pattern apidoc/**.md, excluding obj/**,_site/**, under directory "D:\docfx-test\docfx_project"
[20-07-24 05:27:59.540]Info:No files are found with glob pattern images/**, excluding <none>, under directory "D:\docfx-test\docfx_project"
[20-07-24 05:27:59.560]Info:Markdown engine is markdig
[20-07-24 05:27:59.673]Info:[BuildCore.Build Document]Max parallelism is 8.
[20-07-24 05:28:00.229]Info:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.TocDocumentProcessor]Building 3 file(s) in TocDocumentProcessor(BuildTocDocument)...
[20-07-24 05:28:00.230]Info:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ConceptualDocumentProcessor]Building 0 file(s) in ConceptualDocumentProcessor(BuildConceptualDocument=>CountWord=>ValidateConceptualDocumentMetadata)...
[20-07-24 05:28:00.476]Info:[BuildCore.Build Document.LinkPhaseHandlerWithIncremental.Apply Templates]Applying templates to 3 model(s)...
[20-07-24 05:28:00.939]Info:[BuildCore.Build Document]XRef map exported.
[20-07-24 05:28:01.183]Info:[Postprocess]Manifest file saved to manifest.json.
[20-07-24 05:28:01.259]Info:Completed building documents in 1765.5802 milliseconds.
[20-07-24 05:28:01.262]Info:Completed in 1893.4201 milliseconds


Build succeeded.
        0 Warning(s)
        0 Error(s)

Task                          Duration
--------------------------------------------------
BuildWithConfig               00:00:02.1631551
--------------------------------------------------
Total:                        00:00:02.1631551

Workaround

A hacky workaround I came up with was using StartProcess to invoke the exact docfx.exe command I need which then uses the docfx.json config file. Here is a code snippet of what I did

Task("Build")
    .IsDependentOn("Clean")
    .IsDependentOn("Restore")
    .Does(() =>
{
    var file = File(@".\tools\docfx.console.2.56.1\tools\docfx.exe");
    Information(file);
    StartProcess(file);
});

Granted this is tightly coupled to the version of docfx.console I am using which I specify at the top of my cake.build script.

Context

I am working on a build script that automates generated the DocFx code with a custom configuration file. Without being able to supply the configuration file I need to add additional steps to my build process to run the .exe manually instead of using Cake.

Build Steps

  1. Checkout
  2. Restore
  3. Cake script (init steps, etc.)
  4. docfx command
  5. Cake script (post build steps)

Your Environment

  • Addin version used: 0.13.1 (latest)
  • Cake Version used: 0.38.4 (latest)
  • Operating System: Windows 10

SkyeHoefling avatar Jul 24 '20 17:07 SkyeHoefling

The addin does also just call docfx.exe. If you run the build script with the --verbosity=diagnostic flag you see the executed command:

Executing: "C:/Users/Pascal/Downloads/docfx_project/tools/docfx.console.2.56.1/tools/docfx.exe" build

When running the above command with the working directory set to the root of the attached project I get the same output as when running the build script. When running the above command from any other directory and error is thrown that config file could not be found:

[21-03-29 08:54:54.807]Error:Either provide config file or specify content files to start building documentation.

Based on this behavior everything seems correct to me

pascalberger avatar Mar 29 '21 20:03 pascalberger