[api-documenter] docfx is unable to process YAML files generated by api-documenter

[iuliust]

Summary

Generating markdown docs works just fine, but I'm struggling to make sense of how I'm supposed to make api-documenter work nice with DocFX. Is it supposed to only work with DocFX v3+ ? I've followed the tutorial but there's zero documentation about what I'm supposed to do. Same thing on DocFX's website : there's something about how to make DocFX work nice with Typedoc, but nothing about microsoft's own api-documenter...

Details

[21-01-15 12:24:16.174]Info:[BuildCommand]6 plug-in(s) loaded.
[21-01-15 12:24:16.258]Info:[BuildCommand]No files are found with glob pattern **/*.md, excluding <none>, under directory "C:\julien\web\programmers\Src\WebUi\docs\markdown"
[21-01-15 12:24:16.302]Info:[BuildCommand]Markdown engine is dfm
[21-01-15 12:24:16.430]Info:[BuildCommand.BuildCore.Build Document]Max parallelism is 8.
[21-01-15 12:24:17.169]Warning:[BuildCommand.BuildCore.Build Document.Load]Unable to handle following files: docs/yaml/common.yml,docs/yaml/common/iparameter.yml,docs/yaml/common/gender.yml,docs/yaml/common/iparameterattributes.yml,docs/yaml/common/iuser.yml,docs/yaml/common/egm_label.yml. Do they miss `YamlMime` as the first line of file, e.g.: `### YamlMime:ManagedReference`?
[21-01-15 12:24:18.015]Info:[BuildCommand.BuildCore.Build Document.CompilePhaseHandlerWithIncremental.TocDocumentProcessor]Building 1 file(s) in TocDocumentProcessor(BuildTocDocument)...
[21-01-15 12:24:18.471]Warning:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.TocDocumentProcessor.Save](docs/yaml/toc.yml#L0)Invalid file link:(~/overview/sharepoint.md).
[21-01-15 12:24:18.571]Info:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.UpdateContext]0 external references found in 1 xref maps.
[21-01-15 12:24:18.678]Info:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.UpdateHref](docs/yaml/toc.yml)Unable to find file "~/overview/sharepoint.md" for Href referenced by TOC file "docs/yaml/toc.yml"

Standard questions

Do you know a tutorial for how to make api-documenter work with docFx ? I haven't found anything relevant.

Question	Answer
@microsoft/api-documenter 7.12.4
Operating system?	Windows
Documentation target?	DocFX (YAML)
Would you consider contributing a PR?	Yes
TypeScript compiler version?	4.0.5
Node.js version (node -v)?	15.4.0

[octogonz]

I wrote the API Documenter tutorial. 😇 Sorry it is vague about how to set up DocFX. My own experience with DocFX was using the docs.microsoft.com internal pipeline, which is rather different from the open source DocFX, so I wasn't sure exactly how to do it. If you are able to figure out some step-by-step instructions, we should definitely improve the tutorial.

I know that @rbuckton generated these docs using API Documenter and DocFX. You might look at how that project is set up. His scripts are in this repo.

[iuliust]

Hi, thanks for the (very) quick response, I'd had answered if only I had noticed your message earlier.

Thank you so much for you advice. I just spend ten minutes trying to figure out what @rbuckton is doing in his scripts directory at root, but it looks like it's so far from a simple sample repository that I don't think I could in any way integrate the docfx pipeline in my company's project (although it's probably my best shot at this since I've tried to use docFx). It really is a shame, because I think it's a great tool, just poorly documented.

I've looked for help on the web for hours upon hours, and couldn't find a single tutorial, a simple sample project, about how to integrate api-documenter with docfx. It may look like api-documenter is made to work only with docfx v3, but v3 has no documentation at all, and it's been that way for multiple years (how ironic!). Docfx's v2 doc is completely outdated, and it doesn't even mention api-documenter.

As you may have guessed it, I'm getting a bit frustrated...

[octogonz]

DocFX is just one option. You could also use Docusaurus (like this site) or Jekyll (like API Extractor's own docs) or you can use the @rushstack/api-extractor-model engine to generate your own templates.

In my experience an API reference usually needs to integrate with a project website, which will have its own theme, and navigation, and search. That integration part is often more work than generating the documentation pages themselves.

[rbuckton]

I'm not sure if something has changed in DocFX v3. The version I've been using is 2.52.0.0. For esfx I had to patch api-documenter to work around some issues I was having at the time, but I haven't had time to try out newer versions of either.