feat: add package to generate readme files (#1471)

* feat: add package to generate readme files

* refactor: improvements based on feedback

* feat(generators/readme): generate component props table from prop-types

* refactor(generators/readme): merge enum values column with type column

* refactor(generators/readme): normalize nested objects into multiple table rows

* refactor(generators/readme): support union cases

* refactor: review improvements

* docs: changeset

.changeset/moody-hornets-explain.md

@@ -0,0 +1,6 @@
+---
+"@commercetools-local/generator-readme": patch
+"@commercetools-uikit/avatar": patch
+---
+
+feat: add package to generate readme files

.eslintignore

@@ -5,3 +5,4 @@ node_modules/*
 **/node_modules/*
 vendors/*
 **/raw-components
+generators/**

.github/workflows/main.yml

@@ -44,8 +44,11 @@ jobs:
       - name: Building packages
         run: yarn build
 
+      - name: Running static type checking
+        run: yarn typecheck
+
       - name: Running linters and tests
-        run: yarn run jest --projects jest.{eslint,stylelint,test,bundle}.config.js --reporters jest-silent-reporter
+        run: yarn run jest --projects jest.{eslint,stylelint,test,ts-test,bundle}.config.js --reporters jest-silent-reporter
         env:
           CI: true
 

.prettierrc

@@ -1,5 +1,14 @@
 {
   "trailingComma": "es5",
   "singleQuote": true,
-  "parser": "babel"
+  "overrides": [
+    {
+      "files": "*.mdx",
+      "options": { "parser": "markdown" }
+    },
+    {
+      "files": "*.js",
+      "options": { "parser": "babel" }
+    }
+  ]
 }

@types/rcfile/index.d.ts

@@ -0,0 +1,3 @@
+declare module 'rcfile' {
+  export default function <Config>(pkgName: string): Config;
+}

@types/remark-mdx/index.d.ts

@@ -0,0 +1,7 @@
+declare module 'remark-mdx' {
+  import type { Node } from 'unist';
+  import type { VFile } from 'vfile';
+
+  export type TransformerFn = (tree: Node, file: VFile) => void;
+  export default function (): TransformerFn;
+}

@types/to-vfile/index.d.ts

@@ -0,0 +1,19 @@
+declare module 'to-vfile' {
+  import type { VFileContents, VFileCompatible, VFile } from 'vfile';
+
+  export type FsFileOptions = { encoding?: string; flag?: string };
+
+  export function read(
+    description: VFileContents,
+    options?: FsFileOptions
+  ): Promise<VFileCompatible>;
+  export function write(
+    description: VFile,
+    options?: FsFileOptions
+  ): Promise<void>;
+  export function readSync(
+    description: VFileContents,
+    options?: FsFileOptions
+  ): VFileCompatible;
+  export function writeSync(description: VFile, options?: FsFileOptions): void;
+}

@types/vfile-reporter/index.d.ts

@@ -0,0 +1,5 @@
+declare module 'vfile-reporter' {
+  import type { VFile } from 'vfile';
+
+  export default function report(file: Error | VFile): string;
+}

babel.config.js

@@ -40,6 +40,7 @@ module.exports = function getBabelPreset(api) {
         {
           targets: {
             browsers: ['last 1 versions'],
+            node: 'current',
           },
           corejs: 2,
           // `entry` transforms `@babel/polyfill` into individual requires for
@@ -71,6 +72,7 @@ module.exports = function getBabelPreset(api) {
           autoLabel: !isEnvProduction,
         },
       ],
+      [require('@babel/preset-typescript').default],
     ].filter(Boolean),
     plugins: [
       // Experimental macros support. Will be documented after it's had some time

generators/readme/.gitignore

@@ -0,0 +1 @@
+lib

generators/readme/README.md

@@ -0,0 +1,19 @@
+# Readme generator
+
+A package to generate README files for the React component packages.
+
+## Prerequisites
+
+Each package should have the following fragment files in a `docs` folder:
+
+- `docs/usage-example.js`: a JS example for using the component.
+- `docs/additional-info.md`: (_optional_) any additional information to be rendered AFTER the generated sections.
+- `docs/description.md`: (_optional_) the description of the package, useful if you need to use Markdown syntax. If not provided, it falls back to the `package.json` description field.
+
+## Usage
+
+> The package contains TypeScript file which are not transpiled. To execute the script, the package uses internally `ts-node` CLI, which is already installed in this repository.
+
+```
+yarn generate-readme packages/components/avatar
+```

generators/readme/bin/generate-readme.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+// Do this as the first thing so that any code reading it knows the right env.
+process.env.BABEL_ENV = 'development';
+process.env.NODE_ENV = 'development';
+
+import mri from 'mri';
+import report from 'vfile-reporter';
+import { generate } from '../src/index';
+import { CommandFlags } from '../src/types';
+
+const flags = mri(process.argv.slice(2), {
+  alias: { help: ['h'], boolean: ['dry-run'] },
+});
+const [pathToPackage] = flags._;
+
+const dryRun: boolean = flags['dry-run'] ? true : false;
+
+if (flags.help || !pathToPackage) {
+  console.log(`
+  Usage: generate-readme [path-to-package] [options]
+
+  Displays help information.
+
+  [path-to-package]
+    The path to the package for which the README.md file should be generated.
+    This assumes that the path is the package folder containing a "package.json".
+
+  Options:
+    --dry-run  (optional) Simulate a run, the generated content will be printed to stdout.
+  `);
+  process.exit(0);
+}
+
+const options: CommandFlags = {
+  dryRun,
+};
+
+generate(pathToPackage, options).catch((error) => {
+  console.error(report(error));
+  process.exit(1);
+});

generators/readme/bin/generate_readme.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Get the current directory, following symlinks. See https://stackoverflow.com/a/246128
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do # resolve $SOURCE until the file is no longer a symlink
+  DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE" # if $SOURCE was a relative symlink, we need to resolve it relative to the path where the symlink file was located
+done
+DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+
+# Execute the script using the `ts-node` CLI.
+npx ts-node "$DIR/generate-readme.ts" "$@"

generators/readme/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@commercetools-local/generator-readme",
+  "description": "CLI to generate README files for each package",
+  "version": "1.0.0",
+  "private": true,
+  "bin": {
+    "generate-readme": "./bin/generate_readme.sh"
+  },
+  "main": "./src/index.ts",
+  "scripts": {
+    "start": "tsc --noEmit --watch",
+    "test": "jest --config jest.test.config.js"
+  },
+  "dependencies": {
+    "@types/lodash": "4.14.159",
+    "@types/mdast": "3.0.3",
+    "@types/mri": "1.1.0",
+    "@types/node": "12.12.48",
+    "@types/shelljs": "0.8.8",
+    "@types/unist": "2.0.3",
+    "@types/vfile": "4.0.0",
+    "mri": "1.1.5",
+    "rcfile": "1.0.3",
+    "react-docgen": "5.3.0",
+    "remark-mdx": "1.6.6",
+    "remark-parse": "8.0.2",
+    "remark-stringify": "8.1.0",
+    "shelljs": "0.8.4",
+    "to-vfile": "6.1.0",
+    "unified": "9.0.0",
+    "vfile-reporter": "6.0.1"
+  },
+  "devDependencies": {
+    "ts-node": "8.10.2",
+    "typescript": "3.9.6"
+  }
+}