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] Include namespaces in YAML output #1537

Open
wants to merge 2 commits into
base: master
from

Conversation

@rbuckton
Copy link
Member

rbuckton commented Sep 22, 2019

This builds on #1536 and adds support for including nested namespaces in the YAML output file.

NOTE: This is not a solution in and of itself, as it requires a separate change to the default DocFX templates to properly support namespaces. That PR is forthcoming.

The DocFX PR can be found here: dotnet/docfx#5128

@rbuckton

This comment has been minimized.

Copy link
Member Author

rbuckton commented Sep 23, 2019

I've added a few other things to this PR:

  • Comprehensive IYamlApiFile documentation and a number of updates to typescript.schema.json to indicate all of the YAML properties known to DocFX
  • Include the inheritance hierarchy when available to match the implementation in DocFX
  • Adds Type Aliases and Variables to the YAML output, as I plan to also include them in the PR for DocFX to add proper support for namespaces.
@rbuckton

This comment has been minimized.

Copy link
Member Author

rbuckton commented Sep 23, 2019

Here is a preview of the DocFX template changes I plan to propose:

image

image

@rbuckton

This comment has been minimized.

Copy link
Member Author

rbuckton commented Sep 23, 2019

The related DocFX PR can be found here: dotnet/docfx#5128

@rbuckton rbuckton changed the title Include namespaces in YAML output [api-documenter] Include namespaces in YAML output Sep 25, 2019
@rbuckton rbuckton force-pushed the rbuckton:flattenNamespaces2 branch from bd01fca to 282d13c Sep 25, 2019
@octogonz octogonz added the blocked label Sep 25, 2019
@octogonz

This comment has been minimized.

Copy link
Collaborator

octogonz commented Sep 25, 2019

If I understand right, we can't accept this PR until the DocFX PR dotnet/docfx#5128 is merged and released.

@rbuckton

This comment has been minimized.

Copy link
Member Author

rbuckton commented Oct 12, 2019

This dotnet/docfx#5128 was shipped in DocFX 2.46 last night. Per an offline conversation with @octogonz, we should probably consider putting this behavior behind a flag (or possibly putting the legacy behavior behind a flag) before merging.

Clarification: "This" refers to dotnet/docfx#5128, not this PR.

@octogonz octogonz removed the blocked label Oct 12, 2019
@octogonz

This comment has been minimized.

Copy link
Collaborator

octogonz commented Oct 15, 2019

dotnet/docfx#5128 was shipped in DocFX 2.46 last night

@AlexJerabek The Office Add-ins API has fairly extensive usage of TypeScript namespaces.
Could you test this API Documenter PR branch with your docs? (And if it's not working, maybe confirm whether your DocFX service has version >= 2.46 yet.)

@AlexJerabek

This comment has been minimized.

Copy link
Contributor

AlexJerabek commented Oct 15, 2019

@octogonz This seems to radically change our reference docs. (Internal Staging Site link here. It looks like most of the content is gone.

I can dig deeper to learn what's happening and whether it's our internal tooling pipeline. I might need some guidance from @rbuckton.

That said, this will be challenging timing with Ignite on the horizon. What is the timeline for this update's release?

@octogonz

This comment has been minimized.

Copy link
Collaborator

octogonz commented Oct 16, 2019

This seems to radically change our reference docs. (Internal Staging Site link here.

I don't have permissions to view that site. (Although it might be super helpful if I did... 😉)

It looks like most of the content is gone.

Could you confirm whether you're using DocFX 2.46? My understanding:

Prior to this PR, namespaces were faked by (1) flattening the nested objects to be top-level objects with dotted names, and (2) simulating the nesting in the table of contents.

After this PR, nesting namespaces are now accurately represented in the .yml files. This required updating the DocFX template to render them properly. With the old template, the nested objects are not recognized and get ignored, which may be what caused them to disappear.

What is the timeline for this update's release?

@rbuckton's PR has been open for a while, so we're eager to finally wrap it up. But we definitely would not merge this PR without sign-off from your group.

@rbuckton

This comment has been minimized.

Copy link
Member Author

rbuckton commented Oct 16, 2019

@AlexJerabek I assume you're using customized DocFX templates? It could be a number of things, including:

  • Differences in how UIDs are generated if you are using DocFX overwrite files:

    • In #1337 we updated the UID format to one that is more stable and resilient to collisions (i.e. two declarations of different types with the same name, such as a class and an interface). If you are using overwrite files, the YAML frontmatter may have a uid: field that no longer matches the generated UID.
    • If you are constructing a custom TOC and using UIDs to link items, they may no longer match.
  • Differences between the custom DocFX templates vs the changes in dotnet/docfx#5128

  • Prior to this PR, namespaces were completely removed from the output YAML, i.e:

    namespace Foo {
      class Bar {}
    }

    Would have previously been represented in the TOC as:

    • Foo.Bar

    But now will be represented in the TOC as:

    • Foo
      • Bar

    Also, namespaces can have their own page.

@rbuckton

This comment has been minimized.

Copy link
Member Author

rbuckton commented Oct 16, 2019

If the sources are the ones at https://github.com/OfficeDev/office-js-docs-reference, I can look into the differences later this week.

@AlexJerabek

This comment has been minimized.

Copy link
Contributor

AlexJerabek commented Oct 16, 2019

@rbuckton Correct, our docs are hosted on https://github.com/OfficeDev/office-js-docs-reference. I'm testing these changes on the AlexJ-RSTest branch.

I'll send some time today figuring out if the issue is with our post-processing scripts. I don't want this to block your progress.

@AlexJerabek

This comment has been minimized.

Copy link
Contributor

AlexJerabek commented Oct 16, 2019

One unrelated note that this change highlights:
The docs.microsoft.com platform does not allow TOC folder nodes to have content. There are accessibility issues with that. Those pages are automatically are automatically moved into that folder as a page with the same name.
image
As you can see, the namespace pages are copied into their own folder. Perhaps there's a way to account for this in the naming conventions.

@octogonz

This comment has been minimized.

Copy link
Collaborator

octogonz commented Oct 16, 2019

As you can see, the namespace pages are copied into their own folder. Perhaps there's a way to account for this in the naming conventions.

FYI the Rush Stack table of contents has a similar design, using a "(members)" node. For example:

Capture

The motivation was also for accessibility -- clicking on the container node should expand/collapse the children, rather than navigating to a page.

@octogonz

This comment has been minimized.

Copy link
Collaborator

octogonz commented Oct 25, 2019

@AlexJerabek any progress with this? According to microsoft/TypeScript-Website#80, the TypeScript compiler wants to adopt API Extractor for their docs (🎉yeah!), but they're blocked behind this PR. If you are busy with Ignite, is there a way we could get someone else to help with the validation?

@AlexJerabek

This comment has been minimized.

Copy link
Contributor

AlexJerabek commented Oct 25, 2019

I was really hoping @rbuckton could lend some insight into the changes and help debug from our end. I'm not 100% what you need from us to help debug.

We can always use an older version of the API Extractor/Documenter if need be.

@rbuckton

This comment has been minimized.

Copy link
Member Author

rbuckton commented Oct 25, 2019

My apologies, I've been swamped with other work and haven't been able to look further into this just yet. I will look into it this weekend.

@rbuckton

This comment has been minimized.

Copy link
Member Author

rbuckton commented Oct 29, 2019

I've packed up a version of api-documenter from PR into a tarball so I can more easily test it on the office docs build: microsoft-api-documenter-7.4.6.tar.gz

@rbuckton

This comment has been minimized.

Copy link
Member Author

rbuckton commented Oct 30, 2019

@octogonz

This comment has been minimized.

Copy link
Collaborator

octogonz commented Nov 4, 2019

What's the next step? Are we waiting for @AlexJerabek to do something here?

@rbuckton

This comment has been minimized.

Copy link
Member Author

rbuckton commented Nov 5, 2019

I'm doing some additional investigation on my end right now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.