Improve the structure of the WooCommerce Blocks Handbook (#6429)

* Improve the structure of the WooCommerce Blocks Handbook

Co-authored-by: Rania Lang <[email protected]>

.github/CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thanks for your interest in contributing to WooCommerce Blocks!
 
 If you wish to contribute code, to get started we recommend first reading our [Getting Started Guide](../docs/contributors/getting-started.md).
 
-All other documentation for contributors can be found [in the docs directory](../docs/readme.md).
+All other documentation for contributors can be found [in the docs directory](../docs/README.md).
 
 ## Guidelines
 

.markdownlintignore

@@ -1,4 +1,4 @@
 **/node_modules/**
 **/vendor/**
-docs/extensibility/actions.md
-docs/extensibility/filters.md
+**/extensibility/**/actions.md
+**/extensibility/**/filters.md

README.md

@@ -66,7 +66,7 @@ Run through the ["Writing Your First Block Type" tutorial](https://wordpress.org
 
 For deeper dive, try looking at the [core blocks code,](https://github.com/WordPress/gutenberg/tree/master/packages/block-library/src) or see what [components are available.](https://github.com/WordPress/gutenberg/tree/master/packages/components/src)
 
-To begin contributing to the WooCommerce Blocks plugin, see our [getting started guide](./docs/contributors/getting-started.md) and [developer handbook](./docs/readme.md).
+To begin contributing to the WooCommerce Blocks plugin, see our [getting started guide](./docs/contributors/getting-started.md) and [developer handbook](./docs/README.md).
 
 Other useful docs to explore:
 

assets/js/blocks/classic-template/README.md

@@ -1,4 +1,9 @@
-# Classic Template Block
+# Classic Template Block <!-- omit in toc -->
+
+## Table of Contents <!-- omit in toc -->
+
+-   [Usage](#usage)
+    -   [Props](#props)
 
 The Classic Template block is a placeholder block for specific WooCommerce block templates which are rendered on the server-side when a block theme is active.
 
@@ -21,3 +26,13 @@ This block does not have any customizable options available, so any style or cus
 ```
 
 ![Classic Template Block Single Product](./assets/doc-image-single-product-classic-block.png)
+
+<!-- FEEDBACK -->
+
+---
+
+[We're hiring!](https://woocommerce.com/careers/) Come work with us!
+
+🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/README.md)
+
+<!-- /FEEDBACK -->

assets/js/data/README.md

@@ -11,3 +11,13 @@ The following stores are registered:
 | [schema](./schema/README.md)            | Used for accessing routes. Has more internal usage.                                                                       | SCHEMA_STORE_KEY      |
 | [collections](./collections//README.md) | Holds collections of data indexed by namespace, model name and query string                                               | COLLECTIONS_STORE_KEY |
 | [query-state](./query-state/README.md)  | Holds arbitrary values indexed by context and key. Typically used for tracking state of query objects for a given context | QUERY_STATE_STORE_KEY |
+
+<!-- FEEDBACK -->
+
+---
+
+[We're hiring!](https://woocommerce.com/careers/) Come work with us!
+
+🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/blocks/feature-flags-and-experimental-interfaces.md)
+
+<!-- /FEEDBACK -->

assets/js/data/collections/README.md

@@ -1,4 +1,12 @@
-# Collections Store
+# Collections Store <!-- omit in toc -->
+
+## Table of Contents <!-- omit in toc -->
+
+- [Actions](#actions)
+    - [`receiveCollection( namespace, resourceName, queryString, ids = [], items = [], replace = false )`](#receivecollection-namespace-resourcename-querystring-ids---items---replace--false-)
+- [Selectors](#selectors)
+    - [`getCollection( namespace, resourceName, query = null, ids=[] )`](#getcollection-namespace-resourcename-query--null-ids-)
+    - [`getCollectionHeader( namespace, resourceName, header, query = null, ids = [])`](#getcollectionheader-namespace-resourcename-header-query--null-ids--)
 
 To utilize this store you will import the COLLECTIONS_STORE_KEY in any module referencing it. Assuming `@woocommerce/block-data` is registered as an external pointing to `wc.wcBlocksData` you can import the key via:
 
@@ -51,3 +59,13 @@ If the collection does not have any matching headers for the given arguments, th
 | `header`       | string | The header key for the header.                                                                                           |
 | `query`        | Object | The query arguments for the collection. Eg. `{ order: 'ASC', sortBy: Price }`                                            |
 | `ids`          | Array  | If the collection route has placeholders for ids you provide the values for those placeholders in this array (in order). |
+
+<!-- FEEDBACK -->
+
+---
+
+[We're hiring!](https://woocommerce.com/careers/) Come work with us!
+
+🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/blocks/feature-flags-and-experimental-interfaces.md)
+
+<!-- /FEEDBACK -->

assets/js/data/query-state/README.md

@@ -1,4 +1,10 @@
-# Query State Store
+# Query State Store <!-- omit in toc -->
+
+## Table of contents <!-- omit in toc -->
+
+- [Actions](#actions)
+    - [`setQueryValue( context, queryKey, value )`](#setqueryvalue-context-querykey-value-)
+    - [`setValueForQueryContext( context, value )`](#setvalueforquerycontext-context-value-)
 
 To utilize this store you will import the `QUERY_STATE_STORE_KEY` in any module referencing it. Assuming `@woocommerce/block-data` is registered as an external pointing to `wc.wcBlocksData` you can import the key via:
 
@@ -30,3 +36,13 @@ This will set the query-state for a given context. Typically this is used to set
 | --------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
 | `context` | string | The context for the query state being stored (eg. might be a block name so you can keep query-state specific per block) |
 | `value`   | Object | An object of key/value pairs for the query state being attached to the context.                                         |
+
+<!-- FEEDBACK -->
+
+---
+
+[We're hiring!](https://woocommerce.com/careers/) Come work with us!
+
+🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/blocks/feature-flags-and-experimental-interfaces.md)
+
+<!-- /FEEDBACK -->

assets/js/data/schema/README.md

@@ -1,5 +1,14 @@
 # Schema Store
 
+## Table of contents <!-- omit in toc -->
+
+-   [Table of contents](#table-of-contents)
+-   [Actions](#actions)
+    -   [`receiveRoutes( routes, namespace = '/wc/blocks' )`](#receiveroutes-routes-namespace--wcblocks-)
+-   [Selectors](#selectors)
+    -   [`getRoute( namespace, resourceName, ids = [] )`](#getroute-namespace-resourcename-ids---)
+    -   [`getRoutes( namespace )`](#getroutes-namespace-)
+
 To utilize this store you will import the `SCHEMA_STORE_KEY` in any module referencing it. Assuming `@woocommerce/block-data` is registered as an external pointing to `wc.wcBlocksData` you can import the key via:
 
 ```js
@@ -43,3 +52,13 @@ wp.data.select( SCHEMA_STORE_KEY ).getRoute( '/wc/blocks', 'products', [ 20 ] );
 ### `getRoutes( namespace )`
 
 This will return all the registered routes for the given namespace as a flat array.
+
+<!-- FEEDBACK -->
+
+---
+
+[We're hiring!](https://woocommerce.com/careers/) Come work with us!
+
+🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/blocks/feature-flags-and-experimental-interfaces.md)
+
+<!-- /FEEDBACK -->

assets/js/editor-components/README.md

@@ -1,8 +1,17 @@
-# WooCommerce Blocks - Editor Components
+# Editor Components
 
-These are shared components used in WooCommerce blocks for the editor (Gutenberg) UI. 
+These are shared components used in WooCommerce blocks for the editor (Gutenberg) UI.
 
 Many of our blocks need rich, smart components to provide an interface for selecting or configuring blocks with WooCommerce data. Often there are multiple blocks that need such components. Components in this collection are used in multiple blocks, and may include logic for working with Woo data specifically (e.g. products, shipping methods, product categories).
 
-See [_Components & Storybook_](docs/contributors/storybook.md) doc for more information.
+See [Storybook & Components](docs/contributors/storybook.md) doc for more information.
 
+<!-- FEEDBACK -->
+
+---
+
+[We're hiring!](https://woocommerce.com/careers/) Come work with us!
+
+🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/README.md)
+
+<!-- /FEEDBACK -->

assets/js/editor-components/search-list-control/README.md

@@ -1,4 +1,13 @@
-# SearchListControl
+# SearchListControl <!-- omit in toc -->
+
+## Table of contents <!-- omit in toc -->
+
+-   [Usage](#usage)
+    -   [Props](#props)
+    -   [`list` item structure:](#list-item-structure)
+    -   [`messages` object structure:](#messages-object-structure)
+-   [Usage](#usage)
+    -   [Props](#props)
 
 Component to display a searchable, selectable list of items.
 
@@ -67,3 +76,13 @@ Used implicitly by `SearchListControl` when the `renderItem` prop is omitted.
 | `isSingle`   | Boolean   | `null`  | Whether this should only display a single item (controls radio vs checkbox icon) |
 | `onSelect`   | Function  | `null`  | Callback for selecting the item                                                  |
 | `search`     | String    | `''`    | Search string, used to highlight the substring in the item name                  |
+
+<!-- FEEDBACK -->
+
+---
+
+[We're hiring!](https://woocommerce.com/careers/) Come work with us!
+
+🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/README.md)
+
+<!-- /FEEDBACK -->

assets/js/editor-components/tag/README.md

@@ -1,4 +1,9 @@
-# Tag
+# Tag <!-- omit in toc -->
+
+## Table of contents <!-- omit in toc -->
+
+- [Usage](#usage)
+    - [Props](#props)
 
 This component can be used to show an item styled as a "tag", optionally with an `X` + "remove"
 or with a popover that is shown on click.
@@ -20,3 +25,13 @@ or with a popover that is shown on click.
 | `popoverContents`   | ReactNode                   | `null`  | Contents to display on click in a popover                                           |
 | `remove`            | Function                    | `null`  | A function called when the remove X is clicked. If not used, no X icon will display |
 | `screenReaderLabel` | String                      | `null`  | A more descriptive label for screen reader users. Defaults to the `name` prop       |
+
+<!-- FEEDBACK -->
+
+---
+
+[We're hiring!](https://woocommerce.com/careers/) Come work with us!
+
+🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/README.md)
+
+<!-- /FEEDBACK -->

assets/js/editor-components/text-toolbar-button/README.md

@@ -1,37 +1,41 @@
-# TextToolbarButton
+# TextToolbarButton <!-- omit in toc -->
 
 TextToolbarButton is used in Toolbar for text buttons which show `isToggled` state.
 
-Notes: 
+Notes:
 
-- Gutenberg core has `ToolbarGroup` and `ToolbarButton` in progress. When these are available this component may not be needed.
-- Gutenberg [core `html` block uses regular `Button` in toolbar](https://github.com/WordPress/gutenberg/blob/master/packages/block-library/src/html/edit.js), and sets `is-active` class to trigger "active" styling when button is toggled on.
+-   Gutenberg core has `ToolbarGroup` and `ToolbarButton` in progress. When these are available this component may not be needed.
+-   Gutenberg [core `html` block uses regular `Button` in toolbar](https://github.com/WordPress/gutenberg/blob/master/packages/block-library/src/html/edit.js), and sets `is-active` class to trigger "active" styling when button is toggled on.
 
 ## Usage
 
 Example: two text buttons to select edit modes for cart block.
 
 ```jsx
 <BlockControls>
-  <Toolbar>
-    <TextToolbarButton
-      onClick={ toggleFullCartMode }
-      isToggled={ isFullCartMode }>
-      {  __(
-        'Full Cart',
-        'woo-gutenberg-products-block'
-      ) }
-    </TextToolbarButton>
-    <TextToolbarButton
-      onClick={ toggleFullCartMode }
-      isToggled={ ! isFullCartMode }>
-      {  __(
-        'Empty Cart',
-        'woo-gutenberg-products-block'
-      ) }
-    </TextToolbarButton>
-  </Toolbar>
+	<Toolbar>
+		<TextToolbarButton
+			onClick={ toggleFullCartMode }
+			isToggled={ isFullCartMode }
+		>
+			{ __( 'Full Cart', 'woo-gutenberg-products-block' ) }
+		</TextToolbarButton>
+		<TextToolbarButton
+			onClick={ toggleFullCartMode }
+			isToggled={ ! isFullCartMode }
+		>
+			{ __( 'Empty Cart', 'woo-gutenberg-products-block' ) }
+		</TextToolbarButton>
+	</Toolbar>
 </BlockControls>
 ```
 
+<!-- FEEDBACK -->
 
+---
+
+[We're hiring!](https://woocommerce.com/careers/) Come work with us!
+
+🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/README.md)
+
+<!-- /FEEDBACK -->

assets/js/icons/README.md

@@ -1,4 +1,9 @@
-# Icons
+# Icons <!-- omit in toc -->
+
+## Table of contents <!-- omit in toc -->
+
+-   [Usage](#usage)
+-   [Adding Icons](#adding-icons)
 
 WooCommerce Blocks Icons Library.
 
@@ -25,3 +30,13 @@ Before adding a new icon, make sure the icon is not already included in the [Lib
 3. Remove width and height since they're handled by Icon.
 4. Remove any hardcoded colors on the svg. If necessary, use `CurrentColor`.
 5. Export the Icon in `./library/index.js`.
+
+<!-- FEEDBACK -->
+
+---
+
+[We're hiring!](https://woocommerce.com/careers/) Come work with us!
+
+🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/README.md)
+
+<!-- /FEEDBACK -->

assets/js/legacy/README.md

@@ -1,4 +1,10 @@
-# Legacy Build
+# Legacy Build <!-- omit in toc -->
+
+## Table of Contents <!-- omit in toc -->
+
+- [How does the legacy system work?](#how-does-the-legacy-system-work)
+    - [Aliases](#aliases)
+    - [Webpack Plugin](#webpack-plugin)
 
 This folder is used to hold any components/code that will get exported to the legacy build.
 
@@ -25,7 +31,7 @@ Legacy builds will be identical to the main builds except:
 
 Short answer, through the magic of WebPack! Long answer:
 
-### A. Aliases
+### Aliases
 
 We use aliases for paths covering anything that might need a legacy version. Then we have a dedicated builds for main and legacy code.
 
@@ -47,6 +53,16 @@ Example:
 import { Label } from '@woocommerce/base-components/label';
 ```
 
-### B. Webpack Plugin
+### Webpack Plugin
 
 The second part of the webpack magic is a custom plugin. Located in `bin/fallback-module-directory-webpack-plugin.js`, this custom plugin is used instead of the default Alias plugin. It handles trying a fallback if the original path aliased to does not exist. The fallback is a variation of the aliased path using the provided `search` and `replace` strings when instantiating the plugin. You can see it setup in the `LegacyBlocksConfig.resolve.plugins` property of the `webpack.config.js` file.
+
+<!-- FEEDBACK -->
+
+---
+
+[We're hiring!](https://woocommerce.com/careers/) Come work with us!
+
+🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/README.md)
+
+<!-- /FEEDBACK -->

bin/hook-docs/actions/index.js

@@ -59,7 +59,11 @@ const generate = ( hooks ) => {
 			].filter( Boolean );
 		} ),
 	];
-	createDocs( 'docs/extensibility/actions.md', jsonDocs );
+
+	createDocs(
+		'docs/third-party-developers/extensibility/hooks/actions.md',
+		jsonDocs
+	);
 	console.log( chalk.green( 'Done!' ) );
 };
 

bin/hook-docs/filters/index.js

@@ -59,7 +59,10 @@ const generate = ( hooks ) => {
 			].filter( Boolean );
 		} ),
 	];
-	createDocs( 'docs/extensibility/filters.md', jsonDocs );
+	createDocs(
+		'docs/third-party-developers/extensibility/hooks/filters.md',
+		jsonDocs
+	);
 	console.log( chalk.green( 'Done!' ) );
 };