[api-documenter] Add option to customize or omit toc.yaml

[tylerbutler]

When I run api-documenter, it outputs a toc.yaml file like the following:

items:
  - name: SharePoint Framework reference
    href: ~/overview/sharepoint.md
    items:
      - name: myClass
        uid: myClass
        items:
          - name: Function
            uid: myClass.Function

Those first three lines seem like something that should be omittable or customizable. I know that making api-documenter super flexible is out of scope, but this seems like a behavior that very few users would want.

[octogonz]

Actually I think it's just a bug. If I remember right, DocFX changed the toc.yaml file structure at some point, and api-documenter was never updated. I've seen a couple different repos that have to fix up that file whenever it is generated. We'd happily accept a PR to make the TOC correct, ideally with some input from a DocFX expert to make sure we're following the current best practice for toc.yaml.

@AlexJerabek @davidchesnut FYI

[tylerbutler]

I started working on a fix for this, but with a fresh clone at commit b82072a5202be5642a8ed8f2689be423e28aa66d, I couldn't get api-documenter to build. I see TS compilation errors like:

src/documenters/YamlDocumenter.ts:442:53 - error TS2345: Argument of type 
'import("C:/Users/tylerbu/code/web-build-tools/apps/api-documenter/node_modules/
@microsoft/api-extractor-model/node_modules/@microsoft/tsdoc/lib/nodes/DocSection")
.DocSection' is not assignable to parameter of type 'import("C:/Users/tylerbu/code/web-build-tools/apps/api-documenter/node_modules/@microsoft/tsdoc/lib/nodes/DocSection").DocSection'.

I think the culprit is the upgrade of tsdoc in 139c4a7c5c663805623e39a10b34ab2967fba17d. If I revert to 0.12.8, the build works again. I can file a separate issue on this if needed.

[octogonz]

@tylerbutler the commit b82072a5202be5642a8ed8f2689be423e28aa66d builds fine for me, as does the current master. Even with a clean git clone. I can't repro the build failure.

After pulling, did you remember to run rush install? The full sequence should be like this:

# (after "git pull")
rush install
rush build

If those commands don't work, you could also try a (slower) non-incremental build:

# (after "git pull")
rush install --purge
rush rebuild

If you're still having trouble, could you check your .npmrc to see if it is pointing to a proxy? This would cause you to install NPM packages from your company's registry, instead of from the public registry, which can sometimes cause trouble if the proxy is out of sync. Your .npmrc file will be in a file like C:\Users\<alias>\.npmrc.

[tylerbutler]

@octogonz Thanks for the tips. I'm sure I missed a step or something. The .npmrc could be a problem too; great catch. I'll let you know if I still repro.

[tylerbutler]

Is this addressed by #1265?

[octogonz]

That PR is an early protoype of an effort to make the at TOC more flexible. Office Fabric wants their TOC nodes to be grouped according to manually configured control names (Button, CheckBox, etc) instead of the current arrangement by type (Classes, Enums, etc). Part of this involves introducing a config file to configure api-documenter, which is the right way to resolve your issue here.

The protoype is still in an experimental stage, but if you're okay with that we could add your fix there also pretty easily.

[fhinkel]

I'm having the same problem. toc.yml:

items:
  - name: SharePoint Framework reference
    href: ~/overview/sharepoint.md
    items:

My config doesn't mention Sharepoint anywhere. Is anybody working on removing the SharePoint item from the TOC?

[octogonz]

Is anybody working on removing the SharePoint item from the TOC?

🙄 Yikes, I didn't realize this was still in the code. I know that @rbuckton is using api-documenter's DocFX target to generate the esfx API reference. I wonder how he worked around it.

The eventual plan is to deprecate api-documenter yaml and replace it with api-documenter generate which is driven by a config file. This feature is technically considered "experimental" but I believe some people have been using it in production without problems. There's an example project here that shows how to set up the config files: api-documenter-test. The "tableOfContents" setting allows you to customize the navigation.

@fhinkel Let us know if that solves your problem. BTW if you are interested to contribute a PR, the API Documenter project is one of the easier Rush Stack code bases to work on. All the hard work is already performed by @rushstack/api-extractor-model. 😉

[rbuckton]

🙄 Yikes, I didn't realize this was still in the code. I know that @rbuckton is using api-documenter's DocFX target to generate the esfx API reference. I wonder how he worked around it.

Unfortunately I patch YamlDocumenter as part of my build process 😞: https://github.com/esfx/esfx/blob/master/scripts/docs/patches/api-documenter/overrideTocRoot.js

[ManuelRauber]

Is anybody working on removing the SharePoint item from the TOC?

🙄 Yikes, I didn't realize this was still in the code. I know that @rbuckton is using api-documenter's DocFX target to generate the esfx API reference. I wonder how he worked around it.

The eventual plan is to deprecate api-documenter yaml and replace it with api-documenter generate which is driven by a config file. This feature is technically considered "experimental" but I believe some people have been using it in production without problems. There's an example project here that shows how to set up the config files: api-documenter-test. The "tableOfContents" setting allows you to customize the navigation.

@fhinkel Let us know if that solves your problem. BTW if you are interested to contribute a PR, the API Documenter project is one of the easier Rush Stack code bases to work on. All the hard work is already performed by @rushstack/api-extractor-model. 😉

It's still there 🤓 https://github.com/microsoft/rushstack/blob/main/apps/api-documenter/src/documenters/YamlDocumenter.ts#L127