Skip to content
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

Open
tylerbutler opened this issue Apr 12, 2019 · 10 comments
Open

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

tylerbutler opened this issue Apr 12, 2019 · 10 comments
Labels
bug Something isn't working as intended needs design The next step is for someone to propose the details of an approach for solving the problem

Comments

@tylerbutler
Copy link
Member

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 octogonz added the bug Something isn't working as intended label Apr 12, 2019
@octogonz
Copy link
Collaborator

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

@octogonz octogonz added the needs design The next step is for someone to propose the details of an approach for solving the problem label Apr 12, 2019
@tylerbutler
Copy link
Member Author

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:

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 139c4a7. If I revert to 0.12.8, the build works again. I can file a separate issue on this if needed.

@octogonz
Copy link
Collaborator

octogonz commented Apr 12, 2019

@tylerbutler the commit b82072a 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
Copy link
Member Author

@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
Copy link
Member Author

Is this addressed by #1265?

@octogonz
Copy link
Collaborator

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
Copy link

fhinkel commented Aug 11, 2020

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
Copy link
Collaborator

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
Copy link
Member

🙄 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
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working as intended needs design The next step is for someone to propose the details of an approach for solving the problem
Projects
Status: AE/AD
Development

No branches or pull requests

5 participants