Documentation: Move topic READMEs into docs for discoverability (https://github.com/woocommerce/woocommerce-admin/pull/469)

* Move header/row documentation into the component, so it can be rendered in the external docs

* Move project READMEs into docs folder for exposure in docs site

* Regenerate docs, generate component folder sidebar with component list

* Update format of CSS docs

plugins/woocommerce-admin/bin/generate-docs/lib/file-system.js

@@ -27,9 +27,12 @@ function deleteExistingDocs() {
 	}
 
 	const files = fs.readdirSync( DOCS_FOLDER );
-	files.map( file => fs.unlinkSync( path.resolve( DOCS_FOLDER, file ) ) );
-	fs.rmdirSync( DOCS_FOLDER );
-	fs.mkdirSync( DOCS_FOLDER );
+	files.map( file => {
+		if ( 'README.md' === file ) {
+			return;
+		}
+		fs.unlinkSync( path.resolve( DOCS_FOLDER, file ) );
+	} );
 }
 
 /**
@@ -151,8 +154,8 @@ function writeTableOfContents( files ) {
 		return `  * [${ name }](components/${ doc })`;
 	} ).join( '\n' );
 
-	const TocFile = path.resolve( DOCS_FOLDER, '../_sidebar.md' );
-	fs.writeFileSync( TocFile, '* Home\n\n  * [Overview](/)\n\n* Components\n\n' + TOC );
+	const TocFile = path.resolve( DOCS_FOLDER, '_sidebar.md' );
+	fs.writeFileSync( TocFile, '* [Home](/)\n\n* [Components](components/)\n\n' + TOC + '\n' );
 }
 
 module.exports = {

plugins/woocommerce-admin/client/components/table/table.js

@@ -18,6 +18,37 @@ const getDisplay = cell => cell.display || null;
 
 /**
  * A table component, without the Card wrapper. This is a basic table display, sortable, but no default filtering.
+ *
+ * Row data should be passed to the component as a list of arrays, where each array is a row in the table.
+ * Headers are passed in separately as an array of objects with column-related properties. For example,
+ * this data would render the following table.
+ *
+ * ```js
+ * const headers = [ { label: 'Month' }, { label: 'Orders' }, { label: 'Revenue' } ];
+ * const rows = [
+ * 	[
+ * 		{ display: 'January', value: 1 },
+ * 		{ display: 10, value: 10 },
+ * 		{ display: '$530.00', value: 530 },
+ * 	],
+ * 	[
+ * 		{ display: 'February', value: 2 },
+ * 		{ display: 13, value: 13 },
+ * 		{ display: '$675.00', value: 675 },
+ * 	],
+ * 	[
+ * 		{ display: 'March', value: 3 },
+ * 		{ display: 9, value: 9 },
+ * 		{ display: '$460.00', value: 460 },
+ * 	],
+ * ]
+ * ```
+ *
+ * |   Month  | Orders | Revenue |
+ * | ---------|--------|---------|
+ * | January  |     10 | $530.00 |
+ * | February |     13 | $675.00 |
+ * | March    |      9 | $460.00 |
  */
 class Table extends Component {
 	constructor( props ) {

plugins/woocommerce-admin/docs/_sidebar.md

@@ -1,30 +1,5 @@
-* Home
-
-  * [Overview](/)
-
-* Components
-
-  * [AnimationSlider](components/animation-slider.md)
-  * [Calendar](components/calendar.md)
-  * [Card](components/card.md)
-  * [Chart](components/chart.md)
-  * [Count](components/count.md)
-  * [DropdownButton](components/dropdown-button.md)
-  * [EllipsisMenu](components/ellipsis-menu.md)
-  * [EmptyContent](components/empty-content.md)
-  * [Filters](components/filters.md)
-  * [Flag](components/flag.md)
-  * [Gravatar](components/gravatar.md)
-  * [ImageAsset](components/image-asset.md)
-  * [Link](components/link.md)
-  * [OrderStatus](components/order-status.md)
-  * [Pagination](components/pagination.md)
-  * [ProductImage](components/product-image.md)
-  * [Rating](components/rating.md)
-  * [Search](components/search.md)
-  * [Section](components/section.md)
-  * [SegmentedSelection](components/segmented-selection.md)
-  * [SplitButton](components/split-button.md)
-  * [Summary](components/summary.md)
-  * [Table](components/table.md)
-  * [Tag](components/tag.md)
+* [Overview](/)
+* [Components](components/)
+* [Data](data)
+* [Layout](layout)
+* [CSS Structure](stylesheets)

plugins/woocommerce-admin/docs/components/_sidebar.md

@@ -0,0 +1,28 @@
+* [Home](/)
+
+* [Components](components/)
+
+  * [AnimationSlider](components/animation-slider.md)
+  * [Calendar](components/calendar.md)
+  * [Card](components/card.md)
+  * [Chart](components/chart.md)
+  * [Count](components/count.md)
+  * [DropdownButton](components/dropdown-button.md)
+  * [EllipsisMenu](components/ellipsis-menu.md)
+  * [EmptyContent](components/empty-content.md)
+  * [Filters](components/filters.md)
+  * [Flag](components/flag.md)
+  * [Gravatar](components/gravatar.md)
+  * [ImageAsset](components/image-asset.md)
+  * [Link](components/link.md)
+  * [OrderStatus](components/order-status.md)
+  * [Pagination](components/pagination.md)
+  * [ProductImage](components/product-image.md)
+  * [Rating](components/rating.md)
+  * [Search](components/search.md)
+  * [Section](components/section.md)
+  * [SegmentedSelection](components/segmented-selection.md)
+  * [SplitButton](components/split-button.md)
+  * [Summary](components/summary.md)
+  * [Table](components/table.md)
+  * [Tag](components/tag.md)

plugins/woocommerce-admin/docs/components/table.md

@@ -167,6 +167,37 @@ An array of objects with `label` & `value` properties, which display on a single
 
 A table component, without the Card wrapper. This is a basic table display, sortable, but no default filtering.
 
+Row data should be passed to the component as a list of arrays, where each array is a row in the table.
+Headers are passed in separately as an array of objects with column-related properties. For example,
+this data would render the following table.
+
+```js
+const headers = [ { label: 'Month' }, { label: 'Orders' }, { label: 'Revenue' } ];
+const rows = [
+	[
+		{ display: 'January', value: 1 },
+		{ display: 10, value: 10 },
+		{ display: '$530.00', value: 530 },
+	],
+	[
+		{ display: 'February', value: 2 },
+		{ display: 13, value: 13 },
+		{ display: '$675.00', value: 675 },
+	],
+	[
+		{ display: 'March', value: 3 },
+		{ display: 9, value: 9 },
+		{ display: '$460.00', value: 460 },
+	],
+]
+```
+
+|   Month  | Orders | Revenue |
+| ---------|--------|---------|
+| January  |     10 | $530.00 |
+| February |     13 | $675.00 |
+| March    |      9 | $460.00 |
+
 Props
 -----
 

plugins/woocommerce-admin/docs/data.md

@@ -0,0 +1,4 @@
+Data
+====
+
+TBA, this will document our data implementation.

plugins/woocommerce-admin/docs/index.html

@@ -31,9 +31,6 @@
 			loadSidebar: true,
 			subMaxLevel: 3,
 			search: 'auto',
-			alias: {
-				'/.*/_sidebar.md': '/_sidebar.md',
-			},
 		};
 	</script>
 	<script src="https://unpkg.com/docsify/lib/docsify.min.js"></script>

plugins/woocommerce-admin/docs/stylesheets.md

@@ -13,20 +13,26 @@ To avoid class name collisions between elements of the woo app and to the enclos
 
 Any default export of a folder's `index.js` **must** be prefixed with `woocommerce-` followed by the directory name in which it resides:
 
->.woocommerce-_[ directory name ]_
+```
+.woocommerce-[ directory name ]
+```
 
 (Example: `.woocommerce-card` from `components/card/index.js`)
 
 For any descendant of the top-level (`index.js`) element, prefix using the top-level element's class name separated by two underscores:
 
->.woocommerce-_[ directory name ]_\_\__[ descendant description ]_
+```
+.woocommerce-[ directory name ]__[ descendant description ]
+```
 
 (Example: `.woocommerce-card__title`, or `.woocommerce-ellipsis-menu__item`)
 
 For optional variations of an element or its descendants, you may use a modifier class, but you **must not** apply styles to the modifier class directly; only as an additional selector to the element to which the modifier applies:
 
->.woocommerce-_[ directory name ]_.is-_[ modifier description ]_
->.woocommerce-_[ directory name ]_\_\__[ descendant description ]_.is-_[ modifier description ]_
+```
+.woocommerce-[ directory name ].is-[ modifier description ]
+.woocommerce-[ directory name ]__[ descendant description ].is-[ modifier description ]
+```
 
 (Example: `.woocommerce-ellipsis-menu__item.is-active` )
 
@@ -38,13 +44,17 @@ You may observe that these conventions adhere closely to the [BEM (Blocks, Eleme
 
 All layout classes use the `.woocommerce-layout__` prefix:
 
->.woocommerce-layout\_\__[ section ]_
+```
+.woocommerce-layout__[ section ]
+```
 
 (Example: `.woocommerce-layout__activity-panel` )
 
 If the section has children elements, prefix a description with the section class name:
 
->.woocommerce-layout\_\__[ section ]_-_[ descendant description ]_
+```
+.woocommerce-layout__[ section ]-[ descendant description ]
+```
 
 (Example: `.woocommerce-layout__activity-panel-title` )
 
@@ -52,7 +62,9 @@ If the section has children elements, prefix a description with the section clas
 
 All dashboard components use the `.woocommerce-dashboard__` prefix:
 
->.woocommerce-dashboard\_\__[ section ]_
+```
+.woocommerce-dashboard__[ section ]
+```
 
 (Example: `.woocommerce-dashboard__widget` )