cake-contrib / cake-contrib/Cake.DocFx

Unable To Select docfx.json Configuration File

Open
#95 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
C#
Stars
15
Forks
14
PR merge metrics
No merged PRs in 30d

Description

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](https://github.com/cake-contrib/Cake.DocFx/files/4973425/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](https://cakebuild.net/api/Cake.DocFx/DocFxBuildAliases/E3DBE6C3))
```
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 , 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 , 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

```c#
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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.