Add docs wc #1057

Fionoble · 2023-07-05T21:34:19Z

Background

This PR primarily uses the .dev doc generator + our own custom bash script to scaffold the docs.

What's in this PR

*.doc.ts files for every component in the Admin surface of UI Extensions
Adds missing examples to admin components
Adds *.doc.ts for APIs for admin ui extensions
Adds targets (f.k.a. extension-points) for both block and action extensions
Adds static page json files for the dev-docs for admin extensions

Checklist

I have 🎩'd these changes
I have updated relevant documentation

MitchLillie

This is a lot, thanks Fio! A couple comments and questions

packages/ui-extensions/src/surfaces/admin/extension-points.ts

packages/ui-extensions/docs/surfaces/admin/staticPages/configuration.doc.ts

packages/ui-extensions/src/surfaces/admin/components/shared/index.ts

packages/ui-extensions-react/src/surfaces/admin/components/Form/examples/basic-form.example.tsx

packages/ui-extensions/src/surfaces/admin/components/Form/examples/basic-form.example.ts

packages/ui-extensions/docs/surfaces/admin/staticPages/configuration.doc.ts

tiffanytse

I haven't gone through all the content but mostly just the home page and left a few suggestions and rewrites;

Things to avoid: using words like "We".

Things to do before shipping:

Grep for the word shopify; and make sure it's capitalized when in body content.
Look for instances where it makes sense to markup content with inline code elements for easier reading.

tiffanytse · 2023-07-13T16:04:43Z

packages/ui-extensions/docs/surfaces/admin/staticPages/admin-extensions.doc.ts

+      anchorLink: 'customProtocols',
+      accordionContent: [
+        {
+          title: 'shopify:admin',


@johndcollett is it possible to wrap these in a <code> element so they don't get capitalized as titles since they're reference to actual code strings?

Other option would be to think about the titles more like titles;

Admin protocol, App protocol, Extension protocol, and Relative URLs

and in the body use a code element in the description so it's more obvious what the protocol is.

It would take a code change to be able to do something like that. Right now there are just expecting strings and capitalize the first letter. We can remove that functionality but it might lead to more titles with lowercase letter happening.

packages/ui-extensions/docs/surfaces/admin/staticPages/admin-extensions.doc.ts

packages/ui-extensions/docs/surfaces/admin/staticPages/configuration.doc.ts

tiffanytse · 2023-07-13T16:19:36Z

packages/ui-extensions/docs/surfaces/admin/staticPages/admin-extensions.doc.ts

+      sectionCard: [
+        {
+          name: 'Getting Started',
+          subtitle: 'Get started building your first Admin Extension.',


The subtitle copy is meant to be more of a description of the type of content you're linking to

See Hydrogen for a great example of how to structure these;

https://shopify.dev/docs/api/hydrogen-react

We also need a card to link to the Figma UI Kit, like what Checkout did

https://shopify.dev/docs/api/checkout-ui-extensions#ui-components

Updated these. @lizkhoo-shop do we have a public link for the figma ready?

Still might be a bit wordy. Any thoughts?

No link for the Figma kit yet. We were planning to publish that on July 25, but I think it's okay if there's nothing here for now. You could put '(coming soon)' next to the title.

A few copy notes:

We don't use '.' period punctuation at the end of the big titles

"Admin Extension" should be lower case "admin extension"

Direct API access card - 'SHopify' should be 'Shopify'

packages/ui-extensions/docs/surfaces/admin/staticPages/admin-extensions.doc.ts

tiffanytse

A few more spelling mistakes.

packages/ui-extensions/src/surfaces/admin/extension-points.ts

Co-authored-by: Tiffany Tse <tiffanytse@users.noreply.github.com>

lizkhoo-shop

Looks great!

vividviolet

Thanks for doing this!

Fionoble force-pushed the add-docs-wc branch 19 times, most recently from 63df11f to da0d5f1 Compare July 12, 2023 19:06

Fionoble added 2 commits July 12, 2023 15:14

Add additional admin components

4b142f2

Set up surface specific docs and scripts

99019c6

Fionoble force-pushed the add-docs-wc branch 2 times, most recently from 288c4e2 to 3dcd15b Compare July 12, 2023 20:23

Fionoble marked this pull request as ready for review July 12, 2023 20:29

This comment has been minimized.

Sign in to view

Fionoble requested a review from a team July 12, 2023 20:43

Fionoble force-pushed the add-docs-wc branch from 6f201c1 to 92f2dbe Compare July 12, 2023 21:22

MitchLillie reviewed Jul 12, 2023

View reviewed changes

Fionoble force-pushed the add-docs-wc branch 2 times, most recently from 55dbf59 to 6875593 Compare July 13, 2023 00:31

Fionoble requested review from MitchLillie, elanalynn, olavoasantos and vividviolet July 13, 2023 12:20

vividviolet reviewed Jul 13, 2023

View reviewed changes

tiffanytse reviewed Jul 13, 2023

View reviewed changes

packages/ui-extensions/docs/surfaces/admin/staticPages/admin-extensions.doc.ts Outdated Show resolved Hide resolved

tiffanytse requested changes Jul 13, 2023

View reviewed changes

Fionoble force-pushed the add-docs-wc branch 4 times, most recently from 4f71231 to 216de8c Compare July 14, 2023 00:21

MitchLillie reviewed Jul 14, 2023

View reviewed changes

packages/ui-extensions/src/surfaces/admin/extension-points.ts Outdated Show resolved Hide resolved

Fionoble requested a review from tiffanytse July 14, 2023 18:56

Fionoble force-pushed the add-docs-wc branch from 216de8c to 6b8d1e3 Compare July 14, 2023 19:14

Fionoble requested review from MitchLillie, vividviolet, lizkhoo-shop and johndcollett July 14, 2023 19:22

Fionoble force-pushed the add-docs-wc branch from d18e3fe to 8302d16 Compare July 14, 2023 19:28

Add Admin API docs, aditional APIs and align with checkout docs

3dff93a

Co-authored-by: Tiffany Tse <tiffanytse@users.noreply.github.com>

Fionoble force-pushed the add-docs-wc branch from 8302d16 to 3dff93a Compare July 14, 2023 19:32

lizkhoo-shop approved these changes Jul 14, 2023

View reviewed changes

Remove config docs

27af38f

vividviolet approved these changes Jul 14, 2023

View reviewed changes

Fionoble merged commit 41de9bd into unstable Jul 14, 2023
5 checks passed

shopify-github-actions-access bot mentioned this pull request Jul 17, 2023

Version Packages (2023-04) #1092

Merged

shopify-github-actions-access bot mentioned this pull request Jul 25, 2023

Version Packages (2023-07) #1155

Merged

shopify-github-actions-access bot mentioned this pull request Oct 2, 2023

Version Packages (2023-10) #1406

Merged

Fionoble deleted the add-docs-wc branch December 8, 2023 14:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs wc #1057

Add docs wc #1057

Fionoble commented Jul 5, 2023 •

edited

Loading

This comment has been minimized.

MitchLillie left a comment

tiffanytse left a comment •

edited

Loading

tiffanytse Jul 13, 2023

johndcollett Jul 13, 2023

tiffanytse Jul 13, 2023

lizkhoo-shop Jul 13, 2023 •

edited

Loading

Fionoble Jul 13, 2023

Fionoble Jul 13, 2023

lizkhoo-shop Jul 13, 2023

Fionoble Jul 14, 2023

tiffanytse left a comment

lizkhoo-shop left a comment

vividviolet left a comment

Add docs wc #1057

Add docs wc #1057

Conversation

Fionoble commented Jul 5, 2023 • edited Loading

Background

What's in this PR

Checklist

This comment has been minimized.

MitchLillie left a comment

Choose a reason for hiding this comment

tiffanytse left a comment • edited Loading

Choose a reason for hiding this comment

tiffanytse Jul 13, 2023

Choose a reason for hiding this comment

johndcollett Jul 13, 2023

Choose a reason for hiding this comment

tiffanytse Jul 13, 2023

Choose a reason for hiding this comment

lizkhoo-shop Jul 13, 2023 • edited Loading

Choose a reason for hiding this comment

Fionoble Jul 13, 2023

Choose a reason for hiding this comment

Fionoble Jul 13, 2023

Choose a reason for hiding this comment

lizkhoo-shop Jul 13, 2023

Choose a reason for hiding this comment

Fionoble Jul 14, 2023

Choose a reason for hiding this comment

tiffanytse left a comment

Choose a reason for hiding this comment

lizkhoo-shop left a comment

Choose a reason for hiding this comment

vividviolet left a comment

Choose a reason for hiding this comment

Fionoble commented Jul 5, 2023 •

edited

Loading

tiffanytse left a comment •

edited

Loading

lizkhoo-shop Jul 13, 2023 •

edited

Loading