-
Notifications
You must be signed in to change notification settings - Fork 604
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[api-documenter] Add option to customize or omit toc.yaml #1229
Comments
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. |
I started working on a fix for this, but with a fresh clone at commit b82072a, I couldn't get api-documenter to build. I see TS compilation errors like:
I think the culprit is the upgrade of tsdoc in 139c4a7. If I revert to 0.12.8, the build works again. I can file a separate issue on this if needed. |
@tylerbutler the commit b82072a builds fine for me, as does the current master. Even with a clean After pulling, did you remember to run # (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 |
@octogonz Thanks for the tips. I'm sure I missed a step or something. The |
Is this addressed by #1265? |
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. |
I'm having the same problem. toc.yml:
My config doesn't mention Sharepoint anywhere. Is anybody working on removing the |
🙄 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 @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 |
Unfortunately I patch |
It's still there 🤓 https://github.com/microsoft/rushstack/blob/main/apps/api-documenter/src/documenters/YamlDocumenter.ts#L127 |
When I run api-documenter, it outputs a toc.yaml file like the following:
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.
The text was updated successfully, but these errors were encountered: