feat: docs generator

.eslintignore

@@ -18,4 +18,7 @@ storybook-static
 packages/create-raccoon-app/src/index.js
 
 # Resolve: Expected exception block, space or tab after '//' in comment
-examples/shoreline-nextjs-integration/next-env.d.ts
+examples/shoreline-nextjs-integration/next-env.d.ts
+
+# Resolve: ES2015 module syntax is preferred over namespaces
+packages/docs-generator/src/json-parser

.eslintrc

@@ -9,7 +9,8 @@
     ".vscode/",
     ".cache/",
     "__mocks__/",
-    "__generated__/"
+    "__generated__/",
+    "scripts/format-docs.js"
   ],
   "env": {
     "es2022": true

.gitignore

@@ -80,4 +80,4 @@ out
 .idea
 
 # File system stuff
-**/.DS_Store
+**/.DS_Store

package.json

@@ -28,6 +28,7 @@
     "dev-storybook": "pnpm storybook dev -p 6006",
     "build:storybook": "pnpm build && pnpm storybook build",
     "chromatic": "chromatic --exit-zero-on-changes --build-script-name=build:storybook",
+    "generate-docs": "npm --prefix packages/docs-generator run start",
     "next-docs": "npm --prefix packages/next-docs run dev",
     "build:next-docs": "npm --prefix packages/next-docs run build-docs",
     "commit": "cz",
@@ -85,8 +86,8 @@
     "react-test-renderer": "18.2.0",
     "storybook": "^7.5.3",
     "stylelint": "^15.11.0",
-    "stylelint-prettier": "^4.0.2",
     "stylelint-config-recommended": "^13.0.0",
+    "stylelint-prettier": "^4.0.2",
     "tslib": "2.6.2",
     "tsup": "8.0.1",
     "turbo": "1.4.3",
@@ -108,5 +109,10 @@
     "commitizen": {
       "path": "cz-conventional-changelog"
     }
+  },
+  "pnpm": {
+    "patchedDependencies": {
+      "[email protected]": "packages/docs-generator/patches/[email protected]"
+    }
   }
 }

packages/components/src/button/button.tsx

@@ -74,7 +74,7 @@ export interface ButtonProps extends ComponentPropsWithoutRef<'button'> {
   children: ReactNode
   /**
    * Increase or decrease padding.
-   * @default normal
+   * @default 'normal'
    */
   size?: 'normal' | 'large'
   /**

packages/docs-generator/.prettierrc

@@ -0,0 +1 @@
+"@vtex/prettier-config"

packages/docs-generator/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.

packages/docs-generator/README.md

@@ -0,0 +1,93 @@
+# @vtex/docs-generator
+
+## Description
+
+This is a package that generates documentation from Typescript code. It uses TypeDoc under the hood to generate the documentation from code, and then it passes its output down the pipeline to our own parser, which generates markdown files from TypeDoc's JSON output using Handlebars.
+
+## Usage
+
+Clone the repository, and run `pnpm install` from the root of the repository.
+
+Configure the `docs-generator` package by editing the config variable from `docs-generator/src/index.ts` file. The configuration file is documented on code, so you should be able to understand what each configuration option does.
+
+Run `pnpm run generate-docs` from the root of the repository:
+
+```sh
+pnpm run generate-docs
+```
+
+## Architecture
+
+The `docs-generator` package is composed of two main parts:
+
+- The TypeDoc parser, which is responsible for generating the documentation from Typescript code.
+- The JSON parser, which is responsible for generating markdown files from TypeDoc's JSON output.
+
+### TypeDoc parser
+
+The TypeDoc parser is a wrapper around TypeDoc's Node API. It is responsible for generating the documentation from Typescript code.
+
+### JSON parser
+
+The JSON parser is responsible for generating markdown files from TypeDoc's JSON output. [It is a patch on top of the `typedoc-json-parser` library](../../patches/[email protected]). This patch is necessary because the `typedoc-json-parser` library types are currently broken.
+
+### Code organization
+
+The `docs-generator` package is organized as follows:
+
+```bash
+docs-generator
+├── src
+│   ├── json-parser # The typedoc-json-parser library patch
+│   ├── templates # The Handlebars templates used to generate .mdx files
+│   ├── config.ts # The configuration file for TypeDoc
+│   ├── templates.ts # Handlebars utilities
+│   ├── handlers.ts # A set of functions that handle our different use cases (such as genreating a component documentation)
+│   ├── io.ts # A set of functions that handle IO operations
+│   ├── parser.ts # The JSON parser entrypoint
+│   └── index.ts # The entrypoint of this package where TypeDoc is configured, executed and its output is passed down the pipeline to our JSON parser
+```
+
+## Best practices when writing documentation on code
+
+### For React components
+
+- Always provide a description for the component.
+- Always use the `@example` tag to provide examples of how to use the component. From this tag, a playground is generated.
+- Always provide a description of each property of the component, including the `@default` value when necessary.
+
+Example:
+
+```jsx
+/**
+ * Buttons triggers allow users to identify and start the most important actions in a container.
+ *
+ * @example
+ * <Button>Action label</Button>
+ */
+export function Button(props: ButtonProps) {
+    const {
+        children,
+        size = 'normal',
+        variant = 'secondary',
+        ...rest
+    } = props
+
+    return <button data-size={size} data-variant={variant} {...rest}>{children}</button>
+}
+
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * The size of the button.
+     *
+     * @default 'normal'
+     */
+    size?: 'small' | 'normal' | 'large'
+    /**
+     * The variant of the button.
+     *
+     * @default 'secondary'
+     */
+    variant?: 'primary' | 'secondary' | 'tertiary'
+}
+```

packages/docs-generator/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@vtex/docs-generator",
+  "description": "Generate a custom Markdown documentation from your Typescript code leveraging typedoc",
+  "version": "0.0.0",
+  "type": "module",
+  "private": true,
+  "main": "./src/index.ts",
+  "repository": "vtex/shoreline",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "prebuild": "rm -rf dist",
+    "dev": "tsup --watch",
+    "build": "pnpm run prebuild && tsup",
+    "start": "pnpm run build && node dist/esm/index.js",
+    "start:json": "npx ts-node src/json-parser.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.3",
+    "@types/prettier": "^2.7.3",
+    "typedoc": "0.25.3",
+    "typedoc-plugin-mdn-links": "3.1.4"
+  },
+  "dependencies": {
+    "colorette": "^2.0.20",
+    "handlebars": "^4.7.8",
+    "typedoc-json-parser": "^9.0.1"
+  }
+}