项目作者: josemarluedke

项目描述 :
Extract information from Glimmer components to generate documentation using typescript parser/checker
高级语言: TypeScript
项目地址: git://github.com/josemarluedke/glimmer-docgen-typescript.git
创建时间: 2020-12-26T04:20:23Z
项目社区:https://github.com/josemarluedke/glimmer-docgen-typescript

开源协议:MIT License

下载


glimmer-docgen-typescript

Extract information from Glimmer components to generate documentation using typescript parser/checker.

  • It works with signature interface (Args, Blocks, Element);
  • It works with Glint and gts files;

Compatibility

  • Node.js v20 or above
  • TypeScript v5.0 or above

Installation

  1. npm install --save-dev glimmer-docgen-typescript
  2. # or
  3. yarn add -D glimmer-docgen-typescript

Usage

  1. const docgen = require('glimmer-docgen-typescript');
  2. const fs = require('fs');
  3. const components = docgen.parse([
  4. {
  5. root: __dirname,
  6. pattern: '**/*.ts'
  7. }
  8. ]);
  9. fs.writeFileSync('output.json', JSON.stringify(components));

Options

You can customize the TypeScript parser using the compilerOptions object or pass
the path to the tsconfig.json.

Each source can have it’s own compiler options.

  1. const docgen = require('glimmer-docgen-typescript');
  2. const path = require('path');
  3. docgen.parse([
  4. {
  5. root: __dirname,
  6. pattern: '**/*.ts',
  7. options: {
  8. compilerOptions: {
  9. allowJs: true
  10. // ....
  11. }
  12. }
  13. }
  14. ]);
  15. // or using tsconfig.json
  16. docgen.parse([
  17. {
  18. root: __dirname,
  19. pattern: '**/*.ts',
  20. options: {
  21. tsconfigPath: path.join(__dirname, 'tsconfig.json')
  22. }
  23. }
  24. ]);
  25. // Glint
  26. docgen.parse([
  27. {
  28. root: __dirname,
  29. pattern: 'declarations/components/**/*.d.ts',
  30. options: {
  31. compilerOptions: {
  32. allowJs: true
  33. // ....
  34. }
  35. }
  36. }
  37. ]);

Example

Input

Here is a component definition:

  1. import Component from '@glimmer/component';
  2. interface DrawerArgs {
  3. /** If the Drawer is open */
  4. isOpen: boolean;
  5. /** This called when Drawer should be closed */
  6. onClose: (event: Event) => void;
  7. /**
  8. * If set to false, closing will be prevented
  9. *
  10. * @defaultValue true
  11. */
  12. allowClosing?: boolean;
  13. /**
  14. * The Drawer can appear from any side of the screen. The 'placement'
  15. * option allows to choose where it appears from.
  16. *
  17. * @defaultValue `right`
  18. */
  19. placement?: 'top' | 'bottom' | 'left' | 'right';
  20. /**
  21. * The Drawer size.
  22. *
  23. * @defaultValue `md`
  24. */
  25. size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
  26. }
  27. interface DrawerSignature {
  28. Args: DrawerArgs;
  29. Blocks: {
  30. default: [{ header: unkown, body: unkown, footer: unkown }]
  31. };
  32. Element: HTMLDivElement;
  33. }
  34. /**
  35. * The component description here
  36. *
  37. * @since 1.0.0
  38. */
  39. export default class Drawer extends Component<DrawerSignature> {}

Output

Here is the output:

  1. [
  2. {
  3. package: 'unknown',
  4. module: 'drawer',
  5. name: 'Drawer',
  6. fileName: 'drawer.ts',
  7. Args: [
  8. {
  9. identifier: 'isOpen',
  10. type: { type: 'boolean' },
  11. isRequired: true,
  12. isInternal: false,
  13. description: 'If the Drawer is open',
  14. tags: {},
  15. defaultValue: undefined
  16. },
  17. {
  18. identifier: 'onClose',
  19. type: { type: '(event: Event) => void' },
  20. isRequired: true,
  21. isInternal: false,
  22. description: 'This called when Drawer should be closed',
  23. tags: {},
  24. defaultValue: undefined
  25. },
  26. {
  27. identifier: 'size',
  28. type: {
  29. type: 'enum',
  30. raw: '"xs" | "sm" | "md" | "lg" | "xl" | "full"',
  31. items: [ "'xs'", "'sm'", "'md'", "'lg'", "'xl'", "'full'" ]
  32. },
  33. isRequired: true,
  34. isInternal: false,
  35. description: 'The Drawer size.',
  36. tags: { defaultValue: { name: 'defaultValue', value: '`md`' } },
  37. defaultValue: '`md`'
  38. },
  39. {
  40. identifier: 'allowClosing',
  41. type: { type: 'boolean' },
  42. isRequired: false,
  43. isInternal: false,
  44. description: 'If set to false, closing will be prevented',
  45. tags: { defaultValue: { name: 'defaultValue', value: 'true' } },
  46. defaultValue: 'true'
  47. },
  48. {
  49. identifier: 'placement',
  50. type: {
  51. type: 'enum',
  52. raw: '"top" | "bottom" | "left" | "right"',
  53. items: [ "'top'", "'bottom'", "'left'", "'right'" ]
  54. },
  55. isRequired: false,
  56. isInternal: false,
  57. description: "The Drawer can appear from any side of the screen. The 'placement'\n" +
  58. 'option allows to choose where it appears from.',
  59. tags: { defaultValue: { name: 'defaultValue', value: '`right`' } },
  60. defaultValue: '`right`'
  61. }
  62. ],
  63. Blocks: [
  64. {
  65. identifier: 'default',
  66. type: {
  67. type: 'Array',
  68. raw: '[{ header: unknown; body: unknown; footer: unknown; }]',
  69. items: [
  70. {
  71. identifier: '0',
  72. type: {
  73. type: 'Object',
  74. items: [
  75. {
  76. identifier: 'header',
  77. type: { type: 'unknown' },
  78. isRequired: true,
  79. isInternal: false,
  80. description: '',
  81. tags: {},
  82. defaultValue: undefined
  83. },
  84. {
  85. identifier: 'body',
  86. type: { type: 'unknown' },
  87. isRequired: true,
  88. isInternal: false,
  89. description: '',
  90. tags: {},
  91. defaultValue: undefined
  92. },
  93. {
  94. identifier: 'footer',
  95. type: { type: 'unknown' },
  96. isRequired: true,
  97. isInternal: false,
  98. description: '',
  99. tags: {},
  100. defaultValue: undefined
  101. }
  102. ]
  103. },
  104. isRequired: true,
  105. isInternal: false,
  106. description: '',
  107. tags: {}
  108. }
  109. ]
  110. },
  111. isRequired: true,
  112. isInternal: false,
  113. description: '',
  114. tags: {},
  115. defaultValue: undefined
  116. }
  117. ],
  118. Element: {
  119. identifier: 'Element',
  120. type: { type: 'HTMLDivElement' },
  121. description: '',
  122. url: 'https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement'
  123. },
  124. description: 'The component description here',
  125. tags: { since: { name: 'since', value: '1.0.0' } }
  126. }
  127. ]

This information can be used to create an interface similar to what you can see below:

UI Example

Thanks

Inspired by react-docgen-typescript.

License

This project is licensed under the MIT License.