Skip to content

Commit 94fde8e

Browse files
FionobleFionoble
committed
Fix admin doc gen
1 parent fb8d357 commit 94fde8e

File tree

4 files changed

+133
-69
lines changed

4 files changed

+133
-69
lines changed

‎package.json

+1-2
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,13 @@
2121
"deploy:unstable": "changeset version --snapshot unstable && changeset publish --tag unstable --no-git-tag",
2222
"predeploy:internal": "yarn build",
2323
"deploy:internal": "changeset version --snapshot internal && changeset publish --tag internal --no-git-tag",
24-
"gen-docs:admin": "yarn workspace @shopify/ui-extensions gen-docs:admin",
24+
"gen-docs:admin": "./packages/ui-extensions/docs/surfaces/admin/create-doc-files.sh",
2525
"lint": "loom lint",
2626
"nuke": "rm -rf node_modules && yarn cache clean && rm -rf .loom && git clean -xdf ./packages; rm -rf ./build",
2727
"restore-consumer": "./scripts/restore-consumer.sh",
2828
"restore-consumer-spin": "./scripts/restore-consumer-spin.sh",
2929
"run:ts": "babel-node --extensions .ts,.tsx,.mjs,.js,.json",
3030
"run:ts:watch": "nodemon --ext .ts,.tsx,.mjs,.json,.graphql node_modules/.bin/babel-node --extensions .ts,.tsx,.mjs,.js,.json",
31-
"scaffold-docs:admin": "./packages/ui-extensions/docs/surfaces/admin/create-doc-files.sh \"admin\"",
3231
"type-check": "loom type-check"
3332
},
3433
"devDependencies": {

‎packages/ui-extensions/docs/surfaces/admin/ReadMe.md

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# create-doc-files.sh
2+
3+
A utility script to scaffold documentation files for UI components in the ui-extensions package.
4+
5+
## Usage
6+
7+
```bash
8+
./create-doc-files.sh [-t type] component_name1 [component_name2 ...]
9+
```
10+
11+
### Options
12+
13+
- `-t`: Specifies the type of documentation to create (optional)
14+
- Valid values: `components` or `api`
15+
- Default: `components`
16+
17+
### Arguments
18+
19+
- `component_name1`: Name of the component to document (required)
20+
- `component_name2 ...`: Additional component names (optional)
21+
22+
### Examples
23+
24+
# Create documentation for a single component
25+
26+
```bash
27+
./create-doc-files.sh Button
28+
```
29+
30+
# Create documentation for multiple components
31+
32+
```bash
33+
./create-doc-files.sh Button Card
34+
```
35+
36+
# Create API documentation
37+
38+
```bash
39+
./create-doc-files.sh -t api Toast
40+
```
41+
42+
# Create multiple API docs
43+
44+
```bash
45+
./create-doc-files.sh -t api Modal Toast
46+
```
47+
48+
### Output
49+
50+
For each component, the script creates:
51+
52+
1. A component directory at `packages/ui-extensions/src/surfaces/admin/{type}/{componentName}/`
53+
2. An examples directory containing:
54+
- A TypeScript example (`basic-{lowercase-name}.example.ts`)
55+
- A TSX/Preact example (`basic-{lowercase-name}.example.tsx`)
56+
3. A documentation file (`{ComponentName}.doc.ts`) with a basic template including:
57+
- Component metadata
58+
- Description placeholder
59+
- Example code references
60+
- Category and subcategory settings
61+
62+
The script will skip creating files that already exist to prevent overwriting existing documentation.

‎packages/ui-extensions/docs/surfaces/admin/create-doc-files.sh

+70-66
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,82 @@
11
#!/bin/bash
22

3-
# Validate surface argument
4-
surface="$1"
3+
# Check if at least one component name is provided
4+
if [ $# -eq 0 ]; then
5+
echo "Usage: $0 [-t type] component_name1 [component_name2 ...]"
6+
echo " -t: Type of documentation (api or components, default: components)"
7+
exit 1
8+
fi
59

6-
echo "surface: $surface"
10+
# Parse arguments
11+
type="components" # default value
12+
while getopts "t:" opt; do
13+
case $opt in
14+
t) type="$OPTARG"
15+
if [[ "$type" != "components" && "$type" != "api" ]]; then
16+
echo "Error: type must be either 'components' or 'api'"
17+
exit 1
18+
fi
19+
;;
20+
\?) echo "Invalid option -$OPTARG"
21+
exit 1
22+
;;
23+
esac
24+
done
25+
shift $((OPTIND-1))
726

8-
if [ "$surface" = "admin" ] || [ "$surface" = "checkout" ]; then
9-
echo "Scaffolding docs for ${surface}"
10-
else
11-
echo "ERR: No surface argument provided. Please provide a surface argument (admin or checkout)."
12-
exit 1
13-
fi
1427

15-
# Make this an input to the script
16-
components_dir="src/surfaces/${surface}/components"
17-
# components_dir="./packages/ui-extensions/src/surfaces/${surface}/components"
28+
echo "Scaffolding ${type} docs for admin"
1829

19-
# components_dir="./packages/ui-extensions/src/surfaces/${surface}/api"
30+
base_dir="./packages/ui-extensions/src/surfaces/admin/${type}"
2031

21-
addExamples() {
22-
folder=$1
23-
if [ -d "${folder}/examples" ]; then
24-
example_folder_path="${folder}/examples"
25-
examples=("$example_folder_path"/*)
32+
for componentName in "$@"; do
33+
# Create component directory
34+
folder="${base_dir}/${componentName}"
35+
mkdir -p "$folder"
2636

27-
if [ ${#examples[@]} -eq 1 ] && [[ ${examples[0]} == *"basic"* ]]; then
28-
echo ""
29-
return
30-
fi
37+
examples_dir="${folder}/examples"
38+
mkdir -p "$examples_dir"
39+
40+
docs_file="${folder}/${componentName}.doc.ts"
41+
lowercaseComponentName=$(echo "$componentName" | sed -E 's/([a-z])([A-Z])/\1-\2/g' | tr '[:upper:]' '[:lower:]')
3142

32-
constructed_string="examples: {
33-
description: '',
34-
examples: [
35-
"
36-
for example_file in "${examples[@]}"; do
37-
example_name=$(basename "$example_file" ".example.tsx")
38-
# Skip files starting with "basic-"
39-
if [[ $example_name == basic-* ]]; then
40-
continue
41-
fi
42-
constructed_string+=" {
43-
description: 'TODO: add description',
44-
image: '${example_name}.png',
45-
codeblock: {
46-
tabs: [
47-
{
48-
title: 'Preact',
49-
code: '${example_file}',
50-
language: 'typescript',
51-
},
52-
],
53-
title: 'TODO: add example title',
54-
},
55-
},"$'\n'
56-
done
57-
constructed_string+=" ],
58-
},"
59-
echo "$constructed_string"
43+
# Create TypeScript example file
44+
ts_example="${examples_dir}/basic-${lowercaseComponentName}.example.ts"
45+
if [ ! -f "$ts_example" ]; then
46+
cat << EOF > "$ts_example"
47+
export default function extension() {
48+
const ${componentName} = document.createElement('s-${lowercaseComponentName}');
49+
// Add your s-${componentName} implementation here
50+
document.body.appendChild(${componentName});
51+
};
52+
EOF
53+
echo "Created TS example file for ${componentName}"
6054
fi
61-
}
6255

63-
for folder in "$components_dir"/*; do
64-
if [ -d "$folder" ]; then
65-
if [[ $folder == shared ]]; then
66-
continue
67-
fi
68-
componentName=$(basename "$folder")
69-
docs_file="${folder}/${componentName}.doc.ts"
56+
# Create TSX example file
57+
tsx_example="${examples_dir}/basic-${lowercaseComponentName}.example.tsx"
58+
if [ ! -f "$tsx_example" ]; then
59+
cat << EOF > "$tsx_example"
60+
import '@shopify/ui-extensions/preact';
61+
import {render} from 'preact';
7062
71-
if [ ! -f "$docs_file" ]; then
72-
lowercaseComponentName=$(echo "$componentName" | tr '[:upper:]' '[:lower:]')
73-
cat > "$docs_file" << EOF
63+
export default function extension() {
64+
render(<s-${lowercaseComponentName} />, document.body);
65+
}
66+
EOF
67+
echo "Created TSX example file for ${componentName}"
68+
fi
69+
70+
if [ ! -f "$docs_file" ]; then
71+
cat << EOF > "$docs_file"
7472
import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
7573
7674
const data: ReferenceEntityTemplateSchema = {
7775
name: '${componentName}',
7876
description: '${componentName} is used to ...',
7977
requires: '',
8078
thumbnail: '${lowercaseComponentName}-thumbnail.png',
81-
isVisualComponent: true,
79+
isVisualComponent: $(if [ "$type" = "components" ]; then echo "true"; else echo "false"; fi),
8280
type: '',
8381
definitions: [
8482
{
@@ -87,13 +85,18 @@ const data: ReferenceEntityTemplateSchema = {
8785
type: '${componentName}',
8886
},
8987
],
90-
category: 'Components',
91-
subCategory: 'Feedback',
88+
category: '$(if [ "$type" = "components" ]; then echo "Components"; else echo "API"; fi)',
89+
subCategory: '$(if [ "$type" = "components" ]; then echo "Feedback"; else echo ""; fi)',
9290
defaultExample: {
9391
image: '${lowercaseComponentName}-default.png',
9492
codeblock: {
9593
title: 'TODO: add example title',
9694
tabs: [
95+
{
96+
title: 'Preact',
97+
code: './examples/basic-${lowercaseComponentName}.example.tsx',
98+
language: 'jsx',
99+
},
97100
{
98101
title: 'JS',
99102
code: './examples/basic-${lowercaseComponentName}.example.ts',
@@ -102,12 +105,13 @@ const data: ReferenceEntityTemplateSchema = {
102105
],
103106
},
104107
},
105-
$(addExamples "$folder")
106108
related: [],
107109
};
108110
109111
export default data;
110112
EOF
111-
fi
113+
echo "Created documentation file for ${componentName}"
114+
else
115+
echo "Documentation file for ${componentName} already exists"
112116
fi
113117
done

‎packages/ui-extensions/package.json

-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
"version": "2025.7.0",
44
"scripts": {
55
"docs:admin": "bash ./docs/surfaces/admin/build-docs.sh",
6-
"gen-docs:admin": "bash ./docs/surfaces/admin/create-doc-files.sh \"admin\"",
76
"docs:checkout": "bash ./docs/surfaces/checkout/build-docs.sh",
87
"docs:point-of-sale": "bash ./docs/surfaces/point-of-sale/build-docs.sh",
98
"docs:customer-account": "bash ./docs/surfaces/customer-account/build-docs.sh"

0 commit comments

Comments
 (0)