search

dotnet / docfx

Static site generator for .NET API documentation.
https://dotnet.github.io/docfx/
MIT License
4.08k stars 865 forks source link

Improve debuggability of docfx errors #7796

Open asklar opened 2 years ago

asklar commented 2 years ago

Sometimes I run into issues with docfx when building my docs and get error messages that are not really actionable:

[22-01-03 05:25:23.063]Error:BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.Apply TemplatesError transforming model generated from "api/cppxaml.XamlWindow.yml" using "ManagedReference.html.primary.js". To get the detailed raw model, please run docfx with debug mode --debug. Error running Transform function inside template preprocessor: type is undefined

"type is undefined"... what thing is missing type? The instructions for debug mode aren't very clear, I had to dig into how to use debug mode and realized that it stores some json file in my %temp% folder. There doesn't seem to be more information in the json about the "type is undefined" error either, so I am left having to do trial and error. I'd like docfx to produce actionable error messages, please indicate how to debug these issues.

JeremyCaney commented 2 years ago

Another error that could use an improved error message: When sourcing API metadata, if it’s unable to find any files that meet the glob pattern, it says there’s an error extracting the metadata. But it doesn’t tell you which metadata rule it was following. That can be a bit confusing if there are multiple rules. (Though, at least in this case, it’s pretty straight forward to isolate.)

ghost commented 1 year ago

I am seeing almost the same error as @asklar raised above:

C:\Users\Paytools\Source\repos\paytools-fdn\Paytools.Internal.Documentation\docfx_project\api\Paytools.yml: error ApplyTemplatePreprocessorError: Error transforming model "C:\Users\Paytools\AppData\Local\Temp\docfx\rawmodel\api\Paytools.raw.json" generated from "api/Paytools.yml" using "ManagedReference.html.primary.js". Error running Transform function inside template preprocessor: Cannot read property 'toLowerCase' of undefined

I have no idea what to do with this and adding "--debug" doesn't provide any additional clues. Note that I am running with "namespaceLayout": "nested" (which I know is still experimental). I am guessing there hasn't yet been any progress on this issue.

In the absence of better (i.e., more useful) error messages, an alternative would be to provide a detailed description of how docfx actually works, as that might help users diagnose issues along the build pipeline.

CopilotCoding commented 1 year ago

I have the same problem and no fixes known:

file.yml: error ApplyTemplatePreprocessorError: Error transforming model file.raw.json generated from api/file.yml using "ManagedReference.html.primary.js". Error running Transform function inside template preprocessor: Cannot read property 'toLowerCase' of undefined

mhsimkin commented 1 year ago

I started to run into this issue today. Couldn't figure out what was the root cause. I rebooted and then everything was fine. Could docfx be using node.js internally? Maybe something was being cached that the reboot resolved.

yufeih commented 1 year ago

Could docfx be using node.js internally?

No it isn't using NodeJs, but is using Jint, a different Javascript interpreter under the hook.

ghost commented 1 year ago

All - there are a few small things we can do to improve the error messages, but the fundamental thing we need is documentation that explains how this stuff hangs together, so fault diagnosis can be conducted from a position of understanding, rather than groping in the dark, as we all currently seem to be doing.

Just to re-assure, I am working on this at present but meanwhile regarding Cannot read property 'toLowerCase' of undefined it may pay to take a look at this issue: https://github.com/dotnet/docfx/issues/8540 for guidance.

filzrev commented 9 months ago

Debuggability of docfx JavaScript error are improved by #9694. Above PR adding JavaScript StackTrace information at end of error messages.

Example

C:\projects\docfx.issue4057\docs\api\Examples.Class1.yml: error ApplyTemplatePreprocessorError: Error transforming model generated from "api/Examples.Class1.yml" using "ManagedReference.html.primary.js". To get the detailed raw model, please run docfx with debug mode --debug. Error running Transform function inside template preprocessor: Error: DummyException at ManagedReference.extension.js:2:7