[GSoC] Automatic Documentation System for TypeScript Components #3056

thompsongl · 2020-03-12T18:30:22Z

A better automatic system for documenting EUI TypeScript components. Specifically, we're looking for a better method to extract the acceptable values for each prop on the API. This would be done through automatic transversal of the EUI components itself, combined with the type values from TS and our own inline comments.

Outcome
More accurate, robust prop documentation within the existing "Props" tab for each example section in component documentation. As the EUI team is nearing completion of complete TypeScript conversion, it is possible that the current type and prop traversal system can be entirely replaced.

Related Discussion

[Docs] Allow passing a prop type or interface directly to the props option in the docs #1688; sometimes manual documentation will still be needed/helpful

Interested in working on EUI for Google Summer of Code? See more details here: https://github.com/elastic/gsoc

The text was updated successfully, but these errors were encountered:

thompsongl · 2020-05-11T16:26:07Z

@ashikmeerankutty We'll use this issue to discuss and track modifications to your proposal.

Comment in this thread and then I can assign the issue to you.

ashikmeerankutty · 2020-05-11T16:34:13Z

@thompsongl Thanks!

ashikmeerankutty · 2020-05-21T15:12:22Z

Should I continue this as a separate project outside eui and use the plugin in eui or shift the plugin development inside eui.

thompsongl · 2020-05-21T17:47:15Z

What do you think, @chandlerprall?

chandlerprall · 2020-05-21T18:14:44Z

Let's move it inside eui; makes it easier to observer changes against any set of components

ashikmeerankutty · 2020-05-21T18:56:45Z

Out of curiosity! I just tried adding the plugin to eui. Few observations:

It's taking a lot of time.
Docs info is generated with most of the components.
Build is broken

chandlerprall · 2020-05-21T19:10:47Z

It's taking a lot of time.

Sounds like it's processing TypeScript code 😀

Docs info is generated with most of the components.

Sweet!

Build is broken

The only way to make things better :)

Did you remove the existing ./scripts/babel/proptypes-from-ts-props plugin from babel's config? If not, it might be causing interference.

Next week, I can help look into any issues you're not sure about. If this is too much of a problem right now, there's no rush on moving it into EUI.

ashikmeerankutty · 2020-05-21T19:17:39Z

Did you remove the existing ./scripts/babel/proptypes-from-ts-props plugin from babel's config? If not, it might be causing interference.

No, I will try removing that.

Next week, I can help look into any issues you're not sure about. If this is too much of a problem right now, there's no rush on moving it into EUI.

It doesn't seem to be trouble. I think it's better to continue in eui. I will get a lot of components to try.

ashikmeerankutty · 2020-05-22T17:44:09Z

Just found a webpack loader that uses react-docgen-typescript 😐.
Tried the same in eui and the results seems good 😐.

chandlerprall · 2020-05-27T15:29:26Z

How well does that loader / react-docgen-typescript work with components like EuiButton, which has a mix of our custom PropsForAnchor, PropsForButton, and ExclusiveUnion types? Or EuiBadge which nests those concepts

eui/src/components/badge/badge.tsx

Lines 97 to 102 in c9ae5a0

    
           } & CommonProps & 
        
             ExclusiveUnion<WithIconOnClick, {}> & 
        
             ExclusiveUnion< 
        
               ExclusiveUnion<WithButtonProps, WithAnchorProps>, 
        
               WithSpanProps 
        
             >;

Second aspect of react-docgen-typescript that wasn't great in the past was whether or not it supports types from 3rd party libs / node_modules. Ideally, I think we'd want to white list some like react-beautiful-dnd, either including the types directly or even maybe creating a link to their documentation.

And we also don't want to lose support for generating prop types.

ashikmeerankutty · 2020-05-27T16:59:45Z

With EuiButton and EuiBadge all props are found except the onClick prop 😅. The reason onClick was not found is due to filtering props from node-modules.

react-docgen-typescript support types from node-modules. I tried it with EuiDraggable it displays props from react-beautiful-dnd

ashikmeerankutty · 2020-05-28T07:51:38Z

Preview https://ashikmeerankutty.github.io/eui/

ashikmeerankutty · 2020-05-28T15:39:24Z

react-docgen-typescript allows a propsFilter option.
We could use this to whitelist certain props by name or whitelist props from certain files.

Example of a prop

{
  "prop": {
    "defaultValue": null,
    "description": "",
    "name": "className",
    "parent": {
      "fileName": "eui/node_modules/react-ace/lib/ace.d.ts",
      "name": "IAceEditorProps"
    },
    "required": false,
    "type": {
      "name": "string | undefined"
    }
  }
}

ashikmeerankutty · 2020-06-02T14:58:53Z

@chandlerprall Should I proceed in this way or with the plugin.

chandlerprall · 2020-06-02T19:55:49Z

@thompsongl what do you think, especially in context of feeding these results/data into the docs stuff?

thompsongl · 2020-06-02T20:33:16Z

react-docgen-typescript allows a propsFilter option.

Is this the same for the webpack loader? What deficiencies (if any) does the webpack loader have when compared with the plugin?

chandlerprall · 2020-06-02T20:46:56Z

the webpack loader

Good catch, I dropped that context. We'd (ideally) need a way to get those results without running webpack

ashikmeerankutty · 2020-06-03T04:46:57Z

Is this the same for the webpack loader? What deficiencies (if any) does the webpack loader have when compared with the plugin?

Yes, the webpack-loader provides all the functionalities of react-docgen-typescript. I haven't found any deficiencies with the loader. But I hope creating a custom plugin gives more control on the parser especially for some eui specific needs (if any).

ashikmeerankutty · 2020-06-03T04:49:35Z

Good catch, I dropped that context. We'd (ideally) need a way to get those results without running webpack

Thanks for the clarification. I should continue with the plugin. 😅

ashikmeerankutty · 2020-06-03T18:39:41Z

I think time taken is bit long 😅

chandlerprall · 2020-06-03T20:18:23Z

43 minutes is just a little much 😁

ashikmeerankutty · 2020-06-04T09:28:42Z

With some optimization, I was able to decrease it to 2 minutes 😁 . But there are issues with some components

Should I start a PR now?

ashikmeerankutty · 2020-06-04T09:42:07Z

Also, there are some warnings

chandlerprall · 2020-06-04T16:50:25Z

Should I start a PR now?

Sure!

Also, there are some warnings

Those are coming from the typescript types/interfaces being imported between files, but those values don't exist after the typescript preset takes its pass. We added logic in our custom proptypes-from-ts-props babel plugin. Feel free to ignore these for now, I'm not sure how we want to handle it now vs. in the future.

chandlerprall · 2020-06-09T15:44:08Z

Yes, we'll want to make sure any existing children entries in Props remain; if that requires adding comments let's do so

ashikmeerankutty · 2020-06-09T16:11:51Z

@chandlerprall I can`t think of a suitable comment for the same. Can you please suggest one 😐

chandlerprall · 2020-06-09T17:09:28Z

Let's start with,

ReactNode to render as this component's children

ashikmeerankutty · 2020-06-12T17:00:40Z

There is also an issue with react-docgen-typescript It doesn't produce a result when class extended as React.Component<>.

chandlerprall · 2020-06-12T19:29:10Z

Does it produce results with simple Component<> (imported from React)?

ashikmeerankutty · 2020-06-13T15:28:03Z

Does it produce results with simple Component<> (imported from React)?

Yes

ashikmeerankutty · 2020-06-14T18:33:39Z

I'm facing a weird issue in my plugin. I couldn't figure it till now. Exported types from tsx components aren't working whereas exported types from ts files work fine. It's not an issue related to react-docgen-typescript as I tried the same with my first babel plugin ( that takes 45mins 😐 ). It is working well with tsx files. As a quick workaround, I could move the types to be exported to a new file like types.ts so that it will work well. But I think it's worth fixing this issue inside the plugin itself.
The issue can be found in component such as EuiSuggest.

ashikmeerankutty · 2020-06-14T19:23:39Z

The above issue was fixed using jsx: ts.JsxEmit.React in compiler option for createProgram 😃

ashikmeerankutty · 2020-06-15T11:34:42Z

It seems like this change

eui/src-docs/src/views/accessibility/accessibility_example.js

Lines 119 to 121 in 1259952

    
           props: { 
        
             EuiScreenReaderOnly: ScreenReaderOnlyDocsComponent, 
        
           },

is not necessary while using the new plugin. Can I change it ?

ashikmeerankutty · 2020-06-15T13:11:59Z

Manually checked all components to make sure that props are generated. Props are generated for 90% components even though there are issues with some prop types.
Props are not generated for components with forwardRef and that was fixed in a latest PR in react-docgen-typescript

thompsongl · 2020-06-15T15:47:24Z

is not necessary while using the new plugin. Can I change it ?

What was the reason for adding the ScreenReaderOnlyDocsComponent?

chandlerprall · 2020-06-15T15:50:33Z

Does it produce results with simple Component<> (imported from React)?

Yes

We can convert all React.Component<> to Component<>, that's fine!

ashikmeerankutty · 2020-06-15T16:00:17Z

What was the reason for adding the ScreenReaderOnlyDocsComponent?

The EuiScreenReaderOnly component uses cloneElement and that was creating issues with react-docgen I guess

thompsongl · 2020-06-15T18:20:04Z

The EuiScreenReaderOnly component uses cloneElement and that was creating issues with react-docgen I guess

Go ahead and change it if it is no longer the source of problems

thompsongl · 2020-07-02T18:47:04Z

This would be follow up work to the PR you already have open, but we'd also like to find a way to directly include types and interfaces in the Props table (see #1688)

Tables are good example of this. We manually add complex types and interfaces through a propsInfo hack so that consumers can see subcomponent types in the table. For instance, Pagination is a valuable type, but one that wouldn't come through via simply including EuiTableProps.

ashikmeerankutty · 2020-07-05T12:23:36Z

One workaround for this issue I just found was to create a component called TableProps or OtherProps and let its component extend interfaces that we could display like for the table example:

import React, { FunctionComponent } from 'react';
import { Pagination } from './pagination_bar';
import { EuiTableSortingType } from './table_types';

export interface OtherProps extends Pagination, EuiTableSortingType<any> {}

export const TableProps: FunctionComponent<OtherProps> = () => <div />;

In the generated docgenInfo we could find extendedInterfaces that have all the extended props of the component as separate info.

We could then pass it like TableProps.extendedInterfaces.Pagination to guideSection Page

{
  "description": "",
  "displayName": "TableProps",
  "methods": [],
  "props": {
    "pageIndex": {
      "defaultValue": null,
      "description": "",
      "name": "pageIndex",
      "parent": {
        "fileName": "eui/src/components/basic_table/pagination_bar.tsx",
        "name": "Pagination"
      },
      "required": true,
      "type": {
        "name": "number"
      }
    },
    "pageSize": {
      "defaultValue": null,
      "description": "",
      "name": "pageSize",
      "parent": {
        "fileName": "eui/src/components/basic_table/pagination_bar.tsx",
        "name": "Pagination"
      },
      "required": true,
      "type": {
        "name": "number"
      }
    },
    "totalItemCount": {
      "defaultValue": null,
      "description": "",
      "name": "totalItemCount",
      "parent": {
        "fileName": "eui/src/components/basic_table/pagination_bar.tsx",
        "name": "Pagination"
      },
      "required": true,
      "type": {
        "name": "number"
      }
    },
    "pageSizeOptions": {
      "defaultValue": null,
      "description": "",
      "name": "pageSizeOptions",
      "parent": {
        "fileName": "eui/src/components/basic_table/pagination_bar.tsx",
        "name": "Pagination"
      },
      "required": false,
      "type": {
        "name": "number[]"
      }
    },
    "hidePerPageOptions": {
      "defaultValue": null,
      "description": "",
      "name": "hidePerPageOptions",
      "parent": {
        "fileName": "eui/src/components/basic_table/pagination_bar.tsx",
        "name": "Pagination"
      },
      "required": false,
      "type": {
        "name": "boolean"
      }
    },
    "sort": {
      "defaultValue": null,
      "description": "",
      "name": "sort",
      "parent": {
        "fileName": "eui/src/components/basic_table/table_types.ts",
        "name": "EuiTableSortingType"
      },
      "required": false,
      "type": {
        "name": "{ field: string | number | symbol; direction: \"asc\" | \"desc\"; }"
      }
    },
    "allowNeutralSort": {
      "defaultValue": null,
      "description": "",
      "name": "allowNeutralSort",
      "parent": {
        "fileName": "eui/src/components/basic_table/table_types.ts",
        "name": "EuiTableSortingType"
      },
      "required": false,
      "type": {
        "name": "boolean"
      }
    },
    "enableAllColumns": {
      "defaultValue": null,
      "description": "",
      "name": "enableAllColumns",
      "parent": {
        "fileName": "eui/src/components/basic_table/table_types.ts",
        "name": "EuiTableSortingType"
      },
      "required": false,
      "type": {
        "name": "boolean"
      }
    }
  },
  "extends": [],
  "extendedInterfaces": {
    "Pagination": {
      "__docgenInfo": {
        "description": "",
        "displayName": "Pagination",
        "props": {
          "pageIndex": {
            "defaultValue": null,
            "description": "",
            "name": "pageIndex",
            "parent": {
              "fileName": "eui/src/components/basic_table/pagination_bar.tsx",
              "name": "Pagination"
            },
            "required": true,
            "type": {
              "name": "number"
            }
          },
          "pageSize": {
            "defaultValue": null,
            "description": "",
            "name": "pageSize",
            "parent": {
              "fileName": "eui/src/components/basic_table/pagination_bar.tsx",
              "name": "Pagination"
            },
            "required": true,
            "type": {
              "name": "number"
            }
          },
          "totalItemCount": {
            "defaultValue": null,
            "description": "",
            "name": "totalItemCount",
            "parent": {
              "fileName": "eui/src/components/basic_table/pagination_bar.tsx",
              "name": "Pagination"
            },
            "required": true,
            "type": {
              "name": "number"
            }
          },
          "pageSizeOptions": {
            "defaultValue": null,
            "description": "",
            "name": "pageSizeOptions",
            "parent": {
              "fileName": "eui/src/components/basic_table/pagination_bar.tsx",
              "name": "Pagination"
            },
            "required": false,
            "type": {
              "name": "number[]"
            }
          },
          "hidePerPageOptions": {
            "defaultValue": null,
            "description": "",
            "name": "hidePerPageOptions",
            "parent": {
              "fileName": "eui/src/components/basic_table/pagination_bar.tsx",
              "name": "Pagination"
            },
            "required": false,
            "type": {
              "name": "boolean"
            }
          }
        }
      }
    },
    "EuiTableSortingType": {
      "__docgenInfo": {
        "description": "",
        "displayName": "EuiTableSortingType",
        "props": {
          "sort": {
            "defaultValue": null,
            "description": "",
            "name": "sort",
            "parent": {
              "fileName": "eui/src/components/basic_table/table_types.ts",
              "name": "EuiTableSortingType"
            },
            "required": false,
            "type": {
              "name": "{ field: string | number | symbol; direction: \"asc\" | \"desc\"; }"
            }
          },
          "allowNeutralSort": {
            "defaultValue": null,
            "description": "",
            "name": "allowNeutralSort",
            "parent": {
              "fileName": "eui/src/components/basic_table/table_types.ts",
              "name": "EuiTableSortingType"
            },
            "required": false,
            "type": {
              "name": "boolean"
            }
          },
          "enableAllColumns": {
            "defaultValue": null,
            "description": "",
            "name": "enableAllColumns",
            "parent": {
              "fileName": "eui/src/components/basic_table/table_types.ts",
              "name": "EuiTableSortingType"
            },
            "required": false,
            "type": {
              "name": "boolean"
            }
          }
        }
      }
    }
  }
}

The issue here if two of the interface contains the same props only one among them will be shown.

thompsongl · 2020-07-06T15:34:05Z

Thanks for looking into it. Let's move discussion to that issue (#1688).

thompsongl · 2020-08-13T14:38:09Z

Reopening this so all the tracking continues in one issue.

@ashikmeerankutty, please list any follow-up work to #3554 that you plan on doing (#3554 (review); sorting the props, for instance)

ashikmeerankutty · 2020-08-13T14:43:07Z

Follow ups

Sort the props table in increasing order of prop name
Vertical scroll for functions
Ref as a prop

cchaos · 2020-08-25T20:52:08Z

@ashikmeerankutty Thank you so much for all the work you did on this project!!! 🎉 🎉 I know our all our Elastic engineers are extremely grateful for a more robust and reliable prop table with real Typescript types. The "Extends" bit, while seemingly small, is a game changer! Best of luck to you in future endeavors!

thompsongl · 2020-08-25T20:58:33Z

@ashikmeerankutty I merged #3944, which checks the last box here 🎉

Just make sure you submit all your GSoC evaluations, etc. before the deadline later this week (if you haven't already).

@cchaos is right: we're all thrilled with how it turned out! You did fantastic work over the last few months 🚀

thompsongl · 2020-08-25T20:58:54Z

🙌

ashikmeerankutty · 2020-08-26T05:27:41Z

@cchaos @thompsongl @chandlerprall Thanks for all your support. It was wonderful working with you 😃

thompsongl added the GSoC label Mar 12, 2020

elastic locked and limited conversation to collaborators Mar 12, 2020

Marvin9 mentioned this issue Mar 29, 2020

EuiIcon is missing props #3185

Closed

elastic unlocked this conversation May 11, 2020

thompsongl assigned ashikmeerankutty May 11, 2020

ashikmeerankutty mentioned this issue Jun 4, 2020

[GSOC] Automatic Documentation System for TypeScript Components #3554

Merged

92 tasks

thompsongl mentioned this issue Jul 6, 2020

[Docs] Allow passing a prop type or interface directly to the props option in the docs #1688

Closed

thompsongl closed this as completed in #3554 Aug 13, 2020

thompsongl reopened this Aug 13, 2020

ashikmeerankutty mentioned this issue Aug 14, 2020

Add vertical scroll and text highlighting for functions #3918

Merged

4 tasks

This was referenced Aug 22, 2020

[DOCS] Sort props in docs in ascending order #3944

Merged

Ref in props tab for froward ref components #3956

Merged

thompsongl closed this as completed Aug 25, 2020

[GSoC] Automatic Documentation System for TypeScript Components #3056

[GSoC] Automatic Documentation System for TypeScript Components #3056

Comments

thompsongl commented Mar 12, 2020 • edited by chandlerprall Loading

thompsongl commented May 11, 2020

ashikmeerankutty commented May 11, 2020

ashikmeerankutty commented May 21, 2020

thompsongl commented May 21, 2020

chandlerprall commented May 21, 2020

ashikmeerankutty commented May 21, 2020

chandlerprall commented May 21, 2020

ashikmeerankutty commented May 21, 2020

ashikmeerankutty commented May 22, 2020

chandlerprall commented May 27, 2020 • edited Loading

ashikmeerankutty commented May 27, 2020 • edited Loading

ashikmeerankutty commented May 28, 2020

ashikmeerankutty commented May 28, 2020 • edited Loading

ashikmeerankutty commented Jun 2, 2020

chandlerprall commented Jun 2, 2020

thompsongl commented Jun 2, 2020

chandlerprall commented Jun 2, 2020

ashikmeerankutty commented Jun 3, 2020 • edited Loading

ashikmeerankutty commented Jun 3, 2020

ashikmeerankutty commented Jun 3, 2020

chandlerprall commented Jun 3, 2020

ashikmeerankutty commented Jun 4, 2020 • edited Loading

ashikmeerankutty commented Jun 4, 2020

chandlerprall commented Jun 4, 2020

chandlerprall commented Jun 9, 2020 • edited Loading

ashikmeerankutty commented Jun 9, 2020

chandlerprall commented Jun 9, 2020

ashikmeerankutty commented Jun 12, 2020

chandlerprall commented Jun 12, 2020 • edited Loading

ashikmeerankutty commented Jun 13, 2020

ashikmeerankutty commented Jun 14, 2020

ashikmeerankutty commented Jun 14, 2020

ashikmeerankutty commented Jun 15, 2020

ashikmeerankutty commented Jun 15, 2020

thompsongl commented Jun 15, 2020

chandlerprall commented Jun 15, 2020

ashikmeerankutty commented Jun 15, 2020 • edited Loading

thompsongl commented Jun 15, 2020

thompsongl commented Jul 2, 2020

ashikmeerankutty commented Jul 5, 2020

thompsongl commented Jul 6, 2020

thompsongl commented Aug 13, 2020

ashikmeerankutty commented Aug 13, 2020 • edited by thompsongl Loading

Follow ups

cchaos commented Aug 25, 2020

thompsongl commented Aug 25, 2020

thompsongl commented Aug 25, 2020

ashikmeerankutty commented Aug 26, 2020

thompsongl commented Mar 12, 2020 •

edited by chandlerprall

Loading

chandlerprall commented May 27, 2020 •

edited

Loading

ashikmeerankutty commented May 27, 2020 •

edited

Loading

ashikmeerankutty commented May 28, 2020 •

edited

Loading

ashikmeerankutty commented Jun 3, 2020 •

edited

Loading

ashikmeerankutty commented Jun 4, 2020 •

edited

Loading

chandlerprall commented Jun 9, 2020 •

edited

Loading

chandlerprall commented Jun 12, 2020 •

edited

Loading

ashikmeerankutty commented Jun 15, 2020 •

edited

Loading

ashikmeerankutty commented Aug 13, 2020 •

edited by thompsongl

Loading