Skip to content

Commit 0a774ee

Browse files
FionobleFionoble
committed
Update ab doc gen
1 parent 6e76eba commit 0a774ee

File tree

7 files changed

+115
-4
lines changed

7 files changed

+115
-4
lines changed

‎package.json

+1
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
"predeploy": "yarn build",
1515
"deploy": "changeset publish",
1616
"predeploy:unstable": "yarn build",
17+
"docs:ab": "yarn workspace @shopify/ui-extensions docs:ab",
1718
"docs:admin": "yarn workspace @shopify/ui-extensions docs:admin",
1819
"docs:checkout": "yarn workspace @shopify/ui-extensions docs:checkout",
1920
"docs:point-of-sale": "yarn workspace @shopify/ui-extensions docs:point-of-sale",

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

+4-4
Original file line numberDiff line numberDiff line change
@@ -21,25 +21,25 @@ A utility script to scaffold documentation files for UI components in the ui-ext
2121

2222
### Examples
2323

24-
# Create documentation for a single component
24+
#### Create documentation for a single component
2525

2626
```bash
2727
./create-doc-files.sh Button
2828
```
2929

30-
# Create documentation for multiple components
30+
#### Create documentation for multiple components
3131

3232
```bash
3333
./create-doc-files.sh Button Card
3434
```
3535

36-
# Create API documentation
36+
#### Create API documentation
3737

3838
```bash
3939
./create-doc-files.sh -t api Toast
4040
```
4141

42-
# Create multiple API docs
42+
#### Create multiple API docs
4343

4444
```bash
4545
./create-doc-files.sh -t api Modal Toast

‎packages/ui-extensions/docs/surfaces/admin/build-ab-docs.sh

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
#!/bin/bash
2+
3+
API_VERSION=$1
4+
DOCS_PATH=docs/surfaces/admin
5+
SRC_PATH=src/surfaces/admin
6+
COMPONENTS_DEFINITIONS=src/surfaces/admin/components.d.ts
7+
COMPONENTS_TS=src/surfaces/admin/components.ts
8+
SHOPIFY_DEV_PATH="../../../shopify-dev"
9+
DOT_DEV_DOCS_JSON="$SHOPIFY_DEV_PATH/db/data/docs/templated_apis/app_bridge/generated_docs_data.json"
10+
GENERATED_DOCS_JSON="./$DOCS_PATH/generated/generated_docs_data.json"
11+
12+
fail_and_exit() {
13+
echo "** Failed to generate docs"
14+
echo "See https://vault.shopify.io/page/Extension-Docs~SkgE.md"
15+
exit $1
16+
}
17+
18+
run_sed() {
19+
if [[ "$OSTYPE" == "darwin"* ]]; then
20+
# macOS
21+
sed -i '' "$1" "$2"
22+
else
23+
# Linux and other Unix-like systems
24+
sed -i "$1" "$2"
25+
fi
26+
}
27+
28+
if [ -z $API_VERSION ]
29+
then
30+
API_VERSION="unstable"
31+
echo "Building docs for 'unstable' admin UI extensions API. You can add a calver version argument (e.g. 'yarn docs:admin 2023-07') to generate the docs for a stable version."
32+
else
33+
echo "Building docs for '$API_VERSION' admin UI extensions API."
34+
echo "When generating docs for a stable version, 'unstable' docs are not regenerated. This avoids overwriting other unstable changes that are not included in this version."
35+
echo "If you need to update the 'unstable' version, run this command again without the '$API_VERSION' parameter."
36+
fi
37+
38+
COMPILE_DOCS="yarn tsc --project $DOCS_PATH/tsconfig.ab.docs.json --moduleResolution node --target esNext --module CommonJS && yarn generate-docs --overridePath ./$DOCS_PATH/typeOverride.json --input ./$DOCS_PATH/reference ./$SRC_PATH --typesInput ./$SRC_PATH --output ./$DOCS_PATH/generated"
39+
# COMPILE_STATIC_PAGES="yarn tsc $DOCS_PATH/staticPages/*.doc.ts --moduleResolution node --target esNext --module CommonJS && yarn generate-docs --isLandingPage --input ./$DOCS_PATH/staticPages --output ./$DOCS_PATH/generated"
40+
41+
# Rename components.d.ts to components.ts so it can be picked up be the compiler
42+
cp $COMPONENTS_DEFINITIONS $COMPONENTS_TS
43+
# Remove references to HTMLElement
44+
run_sed "s/typeof globalThis.HTMLElement/any/" $COMPONENTS_TS
45+
46+
eval $COMPILE_DOCS
47+
build_exit=$?
48+
49+
# Remove .doc.js files
50+
find ./ -name '*.doc*.js' -exec rm -r {} \;
51+
# Remove components.ts as it's no longer needed
52+
rm $COMPONENTS_TS
53+
54+
if [ $build_exit -ne 0 ]; then
55+
fail_and_exit $build_exit
56+
fi
57+
58+
# Make sure https://shopify.dev URLs are relative so they work in Spin.
59+
# See https://github.com/Shopify/generate-docs/issues/181
60+
run_sed 's/https:\/\/shopify.dev//gi' ./$DOCS_PATH/generated/generated_docs_data.json
61+
sed_exit=$?
62+
if [ $sed_exit -ne 0 ]; then
63+
fail_and_exit $sed_exit
64+
fi
65+
66+
if [ -d $SHOPIFY_DEV_PATH ]; then
67+
mkdir -p $SHOPIFY_DEV_PATH/db/data/docs/templated_apis/app_bridge
68+
69+
jq 'map(select(.category != "Experimental Components"))' $DOT_DEV_DOCS_JSON > temp1.json
70+
71+
jq 'map(.category = "Experimental Components")' $GENERATED_DOCS_JSON > temp2.json
72+
73+
jq -s '.[0] + .[1]' temp1.json temp2.json > $DOT_DEV_DOCS_JSON
74+
75+
rm temp1.json temp2.json
76+
77+
rsync -a --delete ./$DOCS_PATH/screenshots/ $SHOPIFY_DEV_PATH/app/assets/images/templated-apis-screenshots/admin-extensions/$API_VERSION
78+
79+
if [ -n "$SPIN_SHOPIFY_DEV_SERVICE_FQDN" ]; then
80+
echo "Docs: https://$SPIN_SHOPIFY_DEV_SERVICE_FQDN/docs/api/admin-extensions"
81+
else
82+
echo "Docs: https://shopify-dev.myshopify.io/docs/api/admin-extensions"
83+
fi
84+
else
85+
echo "Not copying docs to shopify-dev because it was not found at $SHOPIFY_DEV_PATH."
86+
fi

‎packages/ui-extensions/docs/surfaces/admin/tsconfig.ab.docs.json

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"compilerOptions": {
3+
"rootDir": "/"
4+
},
5+
"include": [
6+
"./**/*.doc.ts",
7+
"../../../src/surfaces/admin/components/**/*.doc.ts"
8+
],
9+
"exclude": [
10+
"../../../src/surfaces/admin/components/AdminAction/*",
11+
"../../../src/surfaces/admin/components/AdminBlock/*",
12+
"../../../src/surfaces/admin/components/AdminPrintAction/*"
13+
]
14+
}

‎packages/ui-extensions/package.json

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

‎packages/ui-extensions/src/surfaces/admin/components/Button/Button.doc.ts

+5
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,11 @@ const data: ReferenceEntityTemplateSchema = {
3232
code: './examples/basic-button.example.ts',
3333
language: 'js',
3434
},
35+
{
36+
title: 'Preview',
37+
code: './examples/preview.html',
38+
language: 'preview',
39+
},
3540
],
3641
},
3742
},

‎packages/ui-extensions/src/surfaces/admin/components/Button/examples/preview.html

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
<s-stack gap="base">
2+
<s-button variant="primary" onclick="console.log('clicked primary')">Click me</s-button>
3+
<s-button variant="secondary" onclick="console.log('clicked secondary')">Click me</s-button>
4+
</s-stack>

0 commit comments

Comments
 (0)