[api-documenter] Allow customization of table of contents #1265

Vitalius1 · 2019-05-06T08:25:30Z

@octogonz here is a draft of the changes that generates a custom TOC. I tried to make them as generic as possible so that not to break anything for the existing behavior. Also, I've put some comments on some missing types that we need to define. I've verified that without a config file provided it still generates what it was before.

Let me know how else I can help!

cc: @natalieethell , @aditima , @KevinTCoughlin

apps/api-documenter/src/documenters/YamlDocumenter.ts

octogonz · 2019-05-07T01:00:50Z

Could we replace the api-documenter-oufr test with a generic project that isolates specific interesting test cases? Some possible concerns:

These files are somewhat large (e.g. office-ui-fabric-react.api.json is 5MB). This increases the git clone footprint, and GitHub's UI generally chokes up on large files.
The content contains lots of keywords that are unrelated to our projects, and may reduce the quality of search results (e.g. GitHub search).
Although your usage here is okay, in general we're very careful about copying content between GitHub projects to avoid copyright issues. Even if both projects are owned by Microsoft, the third-party notice requirements may be different.

Also, the exercise of creating a different test may help us to think about other possible applications of your feature beyond OUIFR's requirements.

octogonz · 2019-05-07T01:20:48Z

apps/api-documenter/src/yaml/IYamlTocFile.ts

+   * that are matched with the filters provided. Everything else will be placed under a catchAll category
+   * that is highly recommended to be provided.
+   */
+  tocConfig: IYamlTocFile;


I feel like there should be a separation between the toc.yml file format (as specified by DocFX) versus the api-documenter.json file format (which is specific to API Documenter, and may eventually be usable with non-DocFX outputs).

How to ensure then that the TOC map user provides is somewhat aligned with DocFX specification for a TOC?

Vitalius1 · 2019-05-07T02:01:09Z

@octogonz I removed the test I added initially and modified the existing one by adding some inline custom tags. I've also adjusted the debugger to run it and it generates the expected TOC.
The existing test already had lots of different API items to test so we can just grow that generic example project with more edge cases as we find to test.

octogonz · 2019-05-07T03:47:45Z

apps/api-documenter/src/documenters/YamlDocumenter.ts

@@ -490,7 +529,8 @@ export class YamlDocumenter {
    JsonFile.validateNoUndefinedMembers(dataObject);

    let stringified: string = yaml.safeDump(dataObject, {
-      lineWidth: 120
+      lineWidth: 120,
+      noRefs: this._config && this._config.noDuplicateEntries ? true : false


Why is noRefs enabled here? Generally we've shied away from this YAML feature because it introduces reference nodes that interfere with diffs and don't seem to serve any useful purpose. (A properly defined file format normally doesn't include a significant amount of redundant data.) As far as I know the deserialized result is unaffected by this feature, so it's purely cosmetic.

It can be safely removed I believe as it's more of a case-specific thing I tried. In our case, we are loading 4 api.json files: OUFR, styling, utilities, and merge-styles. OUFR on its hand was also re-exporting 2 of these: styling and utilities, so I ended up having lots of duplicates in the navigation. But we will handle this differently now so no need for it now. Forgot to remove it 😄

the reference nodes that you say about are actually introduced if this feature is not toggled on.

…ponding DocumenterConfig class

…emitted by an "api-documenter init" action; for now we'll use this as a sample to track the intended config file contents

…er child class

Vitalius1 · 2019-05-13T18:53:31Z

@iclanton I would appreciate having this experimental addition merged and a release triggered so I can start testing it. Thanks!

apps/api-documenter/.vscode/launch.json

apps/api-documenter/src/cli/GenerateAction.ts

…umenter

apps/api-documenter/src/documenters/DocumenterConfig.ts

apps/api-documenter/src/documenters/ExperimentYamlDocumenter.ts

iclanton · 2019-05-16T06:49:30Z

apps/api-documenter/src/documenters/YamlDocumenter.ts

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.

+// tslint:disable:member-ordering
+


@octogonz - did you ever update this rule?

common/changes/@microsoft/api-documenter/FabricDocumenter_2019-05-06-23-48.json

iclanton · 2019-05-16T06:51:19Z

build-tests/api-documenter-test/etc/markdown/api-documenter-test.docbaseclass.md

@@ -6,6 +6,7 @@

 Example base class

+
 <b>Signature:</b>


Is adding this blank line intentional? Seems like it shouldn't be.

Removed this blank line although it was autogenerated when I ran the test. So with future runs it might get added again.

That makes it seem like a regression was introduced.

That would be highly unlikely because we did not touch the MarkdownDocumenter in this PR. I added a docCategory tag to the test files that might have somehow influenced the output.

iclanton · 2019-05-16T06:52:03Z

build-tests/api-documenter-test/build.js

@@ -26,7 +26,7 @@ if (process.argv.indexOf('--production') >= 0) {

 // Run the API Documenter command-line
 executeCommand('node node_modules/@microsoft/api-documenter/lib/start '
-  + 'yaml --input-folder etc --output-folder etc/yaml');
+  + 'generate --input-folder etc --output-folder etc/yaml');


generate [](start = 5, length = 8)

Should this be an entirely separate test?

The new generate action is meant to replace the yaml action. It's still under experimental title but as we polish it the plan is having just one action generate that will look for an api-documenter.json config file where we would specify what documenter to be used: yaml vs markdown.

iclanton · 2019-05-16T06:53:03Z

apps/api-documenter/src/cli/GenerateAction.ts

+export class GenerateAction extends BaseAction {
+  constructor(parser: ApiDocumenterCommandLine) {
+    super({
+      actionName: 'generate',


generate [](start = 19, length = 8)

This seems like a weird verb. Maybe "experimental-yaml" or something?

See this comment. We discussed it with @octogonz that we might wanna move to a using this generic generate action along with a config file that will command which documenter to be used.

Vitalius1 · 2019-05-16T07:45:31Z

build-tests/api-documenter-test/etc/api-documenter-test.api.json

@@ -17,7 +17,7 @@
        {
          "kind": "Class",
          "canonicalReference": "(DocBaseClass:class)",
-          "docComment": "/**\n * Example base class\n *\n * @public\n */\n",
+          "docComment": "/**\n * Example base class\n *\n * {@docCategory DocBaseClass}\n *\n * @public\n */\n",


@iclanton I bet this change to the documentation is causing the addition of a blank line. MarkdownDocumenter does not know how to handle inline custom tags and it skips {@docCategory DocBaseClass} and is left with \n right after. So this is specific to only this case and this test project. I don't consider it as a regression. Perhaps a MarkdownDocumenter bug that needs to be fixed in a separate PR.

iclanton · 2019-05-16T19:41:21Z

build-tests/api-documenter-test/etc/api-documenter-test.api.json

@@ -17,7 +17,7 @@
        {
          "kind": "Class",
          "canonicalReference": "(DocBaseClass:class)",
-          "docComment": "/**\n * Example base class\n *\n * @public\n */\n",
+          "docComment": "/**\n * Example base class\n *\n * {@docCategory DocBaseClass}\n *\n * @public\n */\n",


Vitalius1 changed the title ~~Fabric documenter~~ [api-documenter] - config file for custom TOCs May 6, 2019

natalieethell reviewed May 6, 2019

View reviewed changes

apps/api-documenter/src/documenters/YamlDocumenter.ts Outdated Show resolved Hide resolved

Vitalius1 marked this pull request as ready for review May 6, 2019 23:40

Vitalius1 requested review from aditima, iclanton and octogonz as code owners May 6, 2019 23:40

octogonz changed the title ~~[api-documenter] - config file for custom TOCs~~ [api-documenter] Allow customization of table of contents May 7, 2019

octogonz force-pushed the FabricDocumenter branch from 105ceef to 303c49d Compare May 7, 2019 01:03

octogonz reviewed May 7, 2019

View reviewed changes

Vitalius1 and others added 15 commits May 6, 2019 22:07

Setup testing

ef91702

Generate schema function

9f4a5e4

setup the config

78f59df

Pipe config file all the way to YamlDocumenter

8d0fdba

Make some changes to how to load configs.

e64c063

Bring generic changes to api-documenter

3e2ddb5

Change a nested if statement

b37f5fa

Add some types to the new logic

15388bd

Change file

252268e

Change the test

4fa3a4e

Adjust debugger

48180b9

Move IYamlTocConfigSchema into an IConfigFile interface with a corres…

5de428b

…ponding DocumenterConfig class

Add an api-documenter-template.json file that in the future could be …

ce0f679

…emitted by an "api-documenter init" action; for now we'll use this as a sample to track the intended config file contents

Extract the experimental functionality into an ExperimentYamlDocument…

336a230

…er child class

Add a new command-line action "api-documenter generate"

34339cd

octogonz force-pushed the FabricDocumenter branch from d77aee0 to 34339cd Compare May 7, 2019 05:15

iclanton reviewed May 16, 2019

View reviewed changes

apps/api-documenter/.vscode/launch.json Outdated Show resolved Hide resolved

iclanton reviewed May 16, 2019

View reviewed changes

apps/api-documenter/src/cli/GenerateAction.ts Outdated Show resolved Hide resolved

iclanton reviewed May 16, 2019

View reviewed changes

apps/api-documenter/src/cli/GenerateAction.ts Outdated Show resolved Hide resolved

iclanton and others added 4 commits May 15, 2019 22:28

Merge branch 'master' into FabricDocumenter

bd3e7d7

Sort imports and remove the debugger file

c65db70

Merge remote-tracking branch 'origin/FabricDocumenter' into FabricDoc…

5dacc8a

…umenter

Remove unnecessary override

6bbaa35

iclanton reviewed May 16, 2019

View reviewed changes

apps/api-documenter/src/documenters/DocumenterConfig.ts Outdated Show resolved Hide resolved

iclanton reviewed May 16, 2019

View reviewed changes

apps/api-documenter/src/documenters/ExperimentYamlDocumenter.ts Outdated Show resolved Hide resolved

iclanton reviewed May 16, 2019

View reviewed changes

apps/api-documenter/src/documenters/ExperimentYamlDocumenter.ts Outdated Show resolved Hide resolved

iclanton reviewed May 16, 2019

View reviewed changes

apps/api-documenter/src/documenters/ExperimentYamlDocumenter.ts Outdated Show resolved Hide resolved

iclanton reviewed May 16, 2019

View reviewed changes

common/changes/@microsoft/api-documenter/FabricDocumenter_2019-05-06-23-48.json Outdated Show resolved Hide resolved

iclanton reviewed May 16, 2019

View reviewed changes

common/changes/@microsoft/api-documenter/FabricDocumenter_2019-05-06-23-48.json Outdated Show resolved Hide resolved

iclanton reviewed May 16, 2019

View reviewed changes

Vitalius1 added 2 commits May 16, 2019 00:13

More feedback addressed

de5a492

Manually remove some blank lines

7218cff

Vitalius1 commented May 16, 2019

View reviewed changes

iclanton approved these changes May 16, 2019

View reviewed changes

iclanton merged commit 99720e6 into microsoft:master May 16, 2019

tylerbutler mentioned this pull request May 20, 2019

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

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[api-documenter] Allow customization of table of contents #1265

[api-documenter] Allow customization of table of contents #1265

Vitalius1 commented May 6, 2019

octogonz commented May 7, 2019

octogonz May 7, 2019

Vitalius1 May 7, 2019 •

edited

Loading

Vitalius1 commented May 7, 2019 •

edited

Loading

octogonz May 7, 2019 •

edited

Loading

Vitalius1 May 7, 2019 •

edited

Loading

Vitalius1 May 7, 2019

Vitalius1 commented May 13, 2019

iclanton May 16, 2019

iclanton May 16, 2019

Vitalius1 May 16, 2019

iclanton May 16, 2019

Vitalius1 May 16, 2019

iclanton May 16, 2019

Vitalius1 May 16, 2019

iclanton May 16, 2019

Vitalius1 May 16, 2019

Vitalius1 May 16, 2019

iclanton May 16, 2019

iclanton May 16, 2019

[api-documenter] Allow customization of table of contents #1265

[api-documenter] Allow customization of table of contents #1265

Conversation

Vitalius1 commented May 6, 2019

octogonz commented May 7, 2019

Choose a reason for hiding this comment

Vitalius1 May 7, 2019 • edited Loading

Choose a reason for hiding this comment

Vitalius1 commented May 7, 2019 • edited Loading

octogonz May 7, 2019 • edited Loading

Choose a reason for hiding this comment

Vitalius1 May 7, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Vitalius1 commented May 13, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Vitalius1 May 7, 2019 •

edited

Loading

Vitalius1 commented May 7, 2019 •

edited

Loading

octogonz May 7, 2019 •

edited

Loading

Vitalius1 May 7, 2019 •

edited

Loading