Quick example creating docs with TypeDoc (#159)

* Quick example creating docs with TypeDoc

* Attempt to fix broken build

* Fix gitignore

.gitignore

@@ -13,6 +13,9 @@ node_modules
 */**/dist
 */**/build
 
+# SDS docs
+@stellar/design-system/docs
+
 # misc
 .DS_Store
 .env

@stellar/design-system-website/docs/intro.md → @stellar/design-system-website/docs/intro.mdx

@@ -5,6 +5,12 @@ sidebar_position: 1
 
 # Intro
 
+Let's discover **Docusaurus in less than 5 minutes**.
+
+## SDS Button component
+
+<ComponentDescription componentName="Button" />
+
 ```tsx live
 <PreviewBlock>
   <Button variant="primary" size="md">
@@ -13,7 +19,19 @@ sidebar_position: 1
 </PreviewBlock>
 ```
 
-Let's discover **Docusaurus in less than 5 minutes**.
+<ComponentProps componentName="Button" />
+
+## SDS Link component
+
+<ComponentDescription componentName="Link" />
+
+```tsx live
+<PreviewBlock>
+  <Link>Test link</Link>
+</PreviewBlock>
+```
+
+<ComponentProps componentName="Link" />
 
 ## Getting Started
 

@stellar/design-system-website/src/components/ComponentDescription/index.tsx

@@ -0,0 +1,24 @@
+import React from "react";
+import SdsDocs from "@stellar/design-system/docs/components.json";
+import { Element } from "@site/src/components/Element";
+
+export const ComponentDescription = ({
+  componentName,
+}: {
+  componentName: string;
+}) => {
+  const component = SdsDocs?.children?.find(
+    (c) => c.name === componentName && c.variant === "declaration",
+  );
+
+  if (!component) {
+    throw Error(`Component "${componentName}" description not found.`);
+  }
+
+  // TODO: split paragraphs /n/n
+  const description = component.comment.summary.map((s) => (
+    <Element text={s.text} kind={s.kind} />
+  ));
+
+  return <p>{description}</p>;
+};

@stellar/design-system-website/src/components/ComponentProps/index.tsx

@@ -0,0 +1,82 @@
+import React from "react";
+import SdsDocs from "@stellar/design-system/docs/components.json";
+import { Element } from "@site/src/components/Element";
+
+export const ComponentProps = ({
+  componentName,
+}: {
+  componentName: string;
+}) => {
+  const component = SdsDocs?.children?.find(
+    (c) => c.name === `${componentName}Props` && c.variant === "declaration",
+  );
+
+  if (!component) {
+    throw Error(`Component "${componentName}" props not found.`);
+  }
+
+  // TODO: reusable component
+  // TODO: split paragraphs /n/n
+  const description = component.comment.summary.map((s) => (
+    <Element text={s.text} kind={s.kind} key={s.id} />
+  ));
+
+  const props = component.children.map((p) => {
+    // TODO: handle this properly
+    const defaultVal = p.comment?.blockTags?.[0]?.content?.[0];
+
+    return (
+      <tr key={p.id}>
+        <td>
+          <code>{p.name}</code>
+        </td>
+        <td>
+          <PropType type={p.type} />
+        </td>
+        <td>
+          {defaultVal ? (
+            <Element text={defaultVal.text} kind={defaultVal.kind} />
+          ) : null}
+        </td>
+        <td>{p?.flags?.isOptional ? "Yes" : ""}</td>
+        {/* TODO: render summary properly */}
+        <td>{p.comment.summary[0].text}</td>
+      </tr>
+    );
+  });
+
+  return (
+    <div>
+      <table>
+        <thead>
+          <tr>
+            <th>Prop</th>
+            <th>Type</th>
+            <th>Default</th>
+            <th>Optional</th>
+            <th>Description</th>
+          </tr>
+        </thead>
+        <tbody>{props}</tbody>
+      </table>
+      <p>{description}</p>
+    </div>
+  );
+};
+
+// TODO: move to its own file
+// TODO: might be combined with Element?
+const PropType = ({ type }: { type: any }) => {
+  // TODO: handle all types
+  switch (type.type) {
+    case "union":
+      return type.types.map((t) => (
+        <>
+          <code>{t.value}</code>{" "}
+        </>
+      ));
+    default:
+      // reference
+      return <code>{type.name || ""}</code>;
+  }
+};

@stellar/design-system-website/src/components/Element.tsx

@@ -0,0 +1,24 @@
+import React from "react";
+
+export type ElementKind = "text" | "code" | "inline-tag";
+
+export const Element = ({
+  text,
+  kind,
+}: {
+  text: string;
+  kind: ElementKind;
+}) => {
+  switch (kind) {
+    case "code":
+      // Remove ``
+      return <code>{text.slice(1, -1)}</code>;
+    case "inline-tag":
+      // TODO: link to inner component
+      return <a href="#">{text}</a>;
+    // text is default
+    default:
+      // TODO: how to handle md links
+      return <>{text}</>;
+  }
+};

@stellar/design-system-website/src/theme/MDXComponents.js

@@ -0,0 +1,9 @@
+import MDXComponents from "@theme-original/MDXComponents";
+import { ComponentDescription } from "@site/src/components/ComponentDescription";
+import { ComponentProps } from "@site/src/components/ComponentProps";
+
+export default {
+  ...MDXComponents,
+  ComponentDescription,
+  ComponentProps,
+};

@stellar/design-system-website/tsconfig.json

@@ -2,6 +2,7 @@
   // This file is not used in compilation. It is here just for a nice editor experience.
   "extends": "@tsconfig/docusaurus/tsconfig.json",
   "compilerOptions": {
-    "baseUrl": "."
+    "baseUrl": ".",
+    "resolveJsonModule": true
   }
 }

@stellar/design-system/package.json

@@ -21,7 +21,8 @@
     "watch:dev": "webpack --watch --mode development",
     "clean": "rimraf ./build",
     "start": "run-p clean watch:tsc watch:dev",
-    "lint-tsc": "tsc --noEmit"
+    "lint-tsc": "tsc --noEmit",
+    "typedoc": "typedoc --options typedoc.json"
   },
   "peerDependencies": {
     "react": ">=18.0.0",
@@ -64,6 +65,7 @@
     "sass-loader": "^13.2.0",
     "style-loader": "^3.3.1",
     "ts-loader": "^9.4.2",
+    "typedoc": "^0.24.8",
     "typescript": "^4.9.5",
     "webpack": "^5.75.0",
     "webpack-cli": "^5.0.1"

@stellar/design-system/src/components/Button/index.tsx

@@ -2,26 +2,47 @@ import React from "react";
 import { Loader } from "../Loader";
 import "./styles.scss";
 
-interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+/**
+ * Including all valid [button attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes)
+ */
+export interface ButtonProps {
+  /** Variant of the button */
   variant:
     | "primary"
     | "secondary"
     | "tertiary"
     | "destructive"
     | "error"
     | "success";
+  /** Size of the button */
   size: "md" | "sm" | "xs";
+  /** Label of the button */
   children?: string | React.ReactNode;
+  /** Icon element */
   icon?: React.ReactNode;
+  /** Position of the icon @defaultValue `right` */
   iconPosition?: "left" | "right";
+  /** Loading state indicator */
   isLoading?: boolean;
+  /** Make label uppercase */
   isUppercase?: boolean;
+  /** Sets width of the button to match the parent container */
   isFullWidth?: boolean;
+  /** Pill shaped button */
   isPill?: boolean;
+  /** Button with extra padding */
   isExtraPadding?: boolean;
 }
 
-export const Button = ({
+interface Props
+  extends ButtonProps,
+    React.ButtonHTMLAttributes<HTMLButtonElement> {}
+
+/**
+ * `Button` is used to trigger an action that is not opening a link (use {@link Link}
+ * instead).
+ */
+export const Button: React.FC<Props> = ({
   variant,
   size,
   children,
@@ -33,7 +54,7 @@ export const Button = ({
   isPill,
   isExtraPadding,
   ...props
-}: ButtonProps): JSX.Element => {
+}) => {
   const additionalClasses = [
     `Button--${variant}`,
     `Button--${size}`,

@stellar/design-system/src/components/Link/index.tsx

@@ -1,18 +1,38 @@
 import React from "react";
 import "./styles.scss";
 
-interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
-  children: string | React.ReactNode;
+/**
+ * Including all valid [anchor element attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes)
+ */
+export interface LinkProps {
+  /** Content of the link */
+  children?: string | React.ReactNode;
+  /** Variant of the link @defaultValue `primary` */
   variant?: "primary" | "secondary";
+  /** Size of the link, will inherit parent size if not set */
   size?: "md" | "sm" | "xs";
+  /** Icon element */
   icon?: React.ReactNode;
+  /** Position of the icon @defaultValue `right` */
   iconPosition?: "left" | "right";
+  /** Disable the link */
   isDisabled?: boolean;
+  /** Underline the link */
   isUnderline?: boolean;
+  /** Make the link uppercase */
   isUppercase?: boolean;
 }
 
-export const Link: React.FC<LinkProps> = ({
+interface Props
+  extends LinkProps,
+    React.AnchorHTMLAttributes<HTMLAnchorElement> {}
+
+/**
+ * `Link` component is a styled HTML anchor (`a`) element. Use `Link` to open links or to navigate to other pages.
+ *
+ * `Link` with external `href` (starting with `http(s)` or `//`) will have attributes `rel="noreferrer noopener"` and `target="_blank"` automatically added.
+ */
+export const Link: React.FC<Props> = ({
   children,
   variant = "primary",
   size,

@stellar/design-system/typedoc.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["src"],
+  "json": "./docs/components.json",
+  "excludeNotDocumented": true
+}

package.json

@@ -12,9 +12,10 @@
   "scripts": {
     "build:sds": "yarn workspace @stellar/design-system build",
     "build:sds-web": "yarn workspace @stellar/design-system-website build",
-    "build": "run-s build:sds build:sds-web",
+    "build": "run-s build:sds docs:sds build:sds-web",
     "start:sds": "yarn workspace @stellar/design-system start",
     "start:sds-web": "yarn workspace @stellar/design-system-website start",
+    "docs:sds": "yarn workspace @stellar/design-system typedoc",
     "tsc:sds": "yarn workspace @stellar/design-system lint-tsc",
     "tsc:sds-web": "yarn workspace @stellar/design-system-website lint-tsc",
     "clean": "rm -rf node_modules && rm -rf */**/node_modules && rm -rf */**/build",