Docs: Add automated theme.json reference documentation

bin/api-docs/gen-theme-reference.js

@@ -0,0 +1,177 @@
+/**
+ * Generates core block documentation using block.json files.
+ * Reads from  : packages/block-library/src
+ * Publishes to: docs/reference-guides/core-blocks.ms
+ */
+
+/**
+ * External dependencies
+ */
+const path = require( 'path' );
+const fs = require( 'fs' );
+const { keys } = require( 'lodash' );
+/**
+ * Path to root project directory.
+ *
+ * @type {string}
+ */
+const ROOT_DIR = path.resolve( __dirname, '../..' );
+
+/**
+ * Path to theme json schema file.
+ *
+ * @type {string}
+ */
+const THEME_JSON_SCHEMA_FILE = path.resolve(
+	ROOT_DIR,
+	path.join( 'schemas', 'json', 'theme.json' )
+);
+
+/**
+ * Path to docs file.
+ *
+ * @type {string}
+ */
+const THEME_JSON_REF_DOC = path.resolve(
+	ROOT_DIR,
+	'docs/reference-guides/theme-json-reference.md'
+);
+
+/**
+ * Start token for matching string in doc file.
+ *
+ * @type {string}
+ */
+const START_TOKEN = '<!-- START TOKEN Autogenerated - DO NOT EDIT -->';
+
+/**
+ * Start token for matching string in doc file.
+ *
+ * @type {string}
+ */
+const END_TOKEN = '<!-- END TOKEN Autogenerated - DO NOT EDIT -->';
+
+/**
+ * Regular expression using tokens for matching in doc file.
+ * Note: `.` does not match new lines, so [^] is used.
+ *
+ * @type {RegExp}
+ */
+const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN );
+
+const themejson = require( THEME_JSON_SCHEMA_FILE );
+
+/**
+ * Convert settings properties to markup.
+ *
+ * @param {Object} struct
+ * @return {string} markup
+ */
+const getSettingsPropertiesMarkup = ( struct ) => {
+	if ( ! ( 'properties' in struct ) ) {
+		return '';
+	}
+	const props = struct.properties;
+	const ks = keys( props );
+	if ( ks.length < 1 ) {
+		return '';
+	}
+
+	let markup = '| Property  | Type   | Default | Props  |\n';
+	markup += '| ---       | ---    | ---    |---   |\n';
+	ks.forEach( ( key ) => {
+		const def = 'default' in props[ key ] ? props[ key ].default : '';
+		const ps =
+			props[ key ].type === 'array'
+				? keys( props[ key ].items.properties ).sort().join( ', ' )
+				: '';
+		markup += `| ${ key } | ${ props[ key ].type } | ${ def } | ${ ps } |\n`;
+	} );
+
+	return markup;
+};
+
+/**
+ * Convert style properties to markup.
+ *
+ * @param {Object} struct
+ * @return {string} markup
+ */
+const getStylePropertiesMarkup = ( struct ) => {
+	if ( ! ( 'properties' in struct ) ) {
+		return '';
+	}
+	const props = struct.properties;
+	const ks = keys( props );
+	if ( ks.length < 1 ) {
+		return '';
+	}
+
+	let markup = '| Property  | Type   |  Props  |\n';
+	markup += '| ---       | ---    |---   |\n';
+	ks.forEach( ( key ) => {
+		const ps =
+			props[ key ].type === 'object'
+				? keys( props[ key ].properties ).sort().join( ', ' )
+				: '';
+		markup += `| ${ key } | ${ props[ key ].type } | ${ ps } |\n`;
+	} );
+
+	return markup;
+};
+
+/**
+ * Parses a section for description and properties and
+ * returns a marked up version.
+ *
+ * @param {string} title
+ * @param {Object} data
+ * @param {string} type settings|style
+ * @return {string} markup
+ */
+const getSectionMarkup = ( title, data, type ) => {
+	const markupFn =
+		type === 'settings'
+			? getSettingsPropertiesMarkup
+			: getStylePropertiesMarkup;
+
+	return `
+### ${ title }
+
+${ data.description }
+
+${ markupFn( data ) }
+---
+`;
+};
+
+let autogen = '';
+
+// Settings
+const settings = themejson.definitions.settingsProperties.properties;
+const settingSections = keys( settings );
+autogen += '## Settings' + '\n\n';
+settingSections.forEach( ( section ) => {
+	autogen += getSectionMarkup( section, settings[ section ], 'settings' );
+} );
+
+// Styles
+const styles = themejson.definitions.stylesProperties.properties;
+const styleSections = keys( styles );
+autogen += '## Styles' + '\n\n';
+styleSections.forEach( ( section ) => {
+	autogen += getSectionMarkup( section, styles[ section ], 'styles' );
+} );
+
+// Read existing file to wrap auto generated content.
+let docsContent = fs.readFileSync( THEME_JSON_REF_DOC, {
+	encoding: 'utf8',
+	flag: 'r',
+} );
+
+// Replace auto generated part with new generated docs.
+autogen = START_TOKEN + '\n' + autogen + '\n' + END_TOKEN;
+docsContent = docsContent.replace( TOKEN_PATTERN, autogen );
+
+// Write back out.
+fs.writeFileSync( THEME_JSON_REF_DOC, docsContent, { encoding: 'utf8' } );

docs/manifest.json

@@ -593,6 +593,12 @@
 		"markdown_source": "../docs/reference-guides/richtext.md",
 		"parent": "reference-guides"
 	},
+	{
+		"title": "Theme.json Reference",
+		"slug": "theme-json-reference",
+		"markdown_source": "../docs/reference-guides/theme-json-reference.md",
+		"parent": "reference-guides"
+	},
 	{
 		"title": "Component Reference",
 		"slug": "components",

docs/reference-guides/theme-json-reference.md

@@ -0,0 +1,160 @@
+# Theme.json Reference
+
+This reference guide lists the settings and style properties defined in the theme.json schema. See the [theme.json how to guide](/docs/how-to-guides/themes/theme-json.md) for examples and guide on how to use the theme.json file in your theme.
+
+<!-- START TOKEN Autogenerated - DO NOT EDIT -->
+## Settings
+
+
+### appearanceTools
+
+Setting that enables the following UI tools:
+
+- border: color, radius, style, width
+- color: link
+- spacing: blockGap, margin, padding
+- typography: lineHeight
+
+
+---
+
+### border
+
+Settings related to borders.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| color | boolean | false |  |
+| radius | boolean | false |  |
+| style | boolean | false |  |
+| width | boolean | false |  |
+
+---
+
+### color
+
+Settings related to colors.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| background | boolean | true |  |
+| custom | boolean | true |  |
+| customDuotone | boolean | true |  |
+| customGradient | boolean | true |  |
+| defaultGradients | boolean | true |  |
+| defaultPalette | boolean | true |  |
+| duotone | array |  | colors, name, slug |
+| gradients | array |  | gradient, name, slug |
+| link | boolean | false |  |
+| palette | array |  | color, name, slug |
+| text | boolean | true |  |
+
+---
+
+### layout
+
+Settings related to layout.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| contentSize | string |  |  |
+| wideSize | string |  |  |
+
+---
+
+### spacing
+
+Settings related to spacing.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| blockGap | undefined | null |  |
+| margin | boolean | false |  |
+| padding | boolean | false |  |
+| units | array | px,em,rem,vh,vw,% |  |
+
+---
+
+### typography
+
+Settings related to typography.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| customFontSize | boolean | true |  |
+| fontStyle | boolean | true |  |
+| fontWeight | boolean | true |  |
+| letterSpacing | boolean | true |  |
+| lineHeight | boolean | false |  |
+| textDecoration | boolean | true |  |
+| textTransform | boolean | true |  |
+| dropCap | boolean | true |  |
+| fontSizes | array |  | name, size, slug |
+| fontFamilies | array |  | fontFamily, name, slug |
+
+---
+
+### custom
+
+Generate custom CSS custom properties of the form `--wp--custom--{key}--{nested-key}: {value};`. `camelCased` keys are transformed to `kebab-case` as to follow the CSS property naming schema. Keys at different depth levels are separated by `--`, so keys should not include `--` in the name.
+
+
+---
+## Styles
+
+
+### border
+
+Border styles.
+
+| Property  | Type   |  Props  |
+| ---       | ---    |---   |
+| color | string |  |
+| radius | string |  |
+| style | string |  |
+| width | string |  |
+
+---
+
+### color
+
+Color styles.
+
+| Property  | Type   |  Props  |
+| ---       | ---    |---   |
+| background | string |  |
+| gradient | string |  |
+| text | string |  |
+
+---
+
+### spacing
+
+Spacing styles.
+
+| Property  | Type   |  Props  |
+| ---       | ---    |---   |
+| blockGap | string |  |
+| margin | object | bottom, left, right, top |
+| padding | object | bottom, left, right, top |
+
+---
+
+### typography
+
+Typography styles.
+
+| Property  | Type   |  Props  |
+| ---       | ---    |---   |
+| fontFamily | string |  |
+| fontSize | string |  |
+| fontStyle | string |  |
+| fontWeight | string |  |
+| letterSpacing | string |  |
+| lineHeight | string |  |
+| textDecoration | string |  |
+| textTransform | string |  |
+
+---
+
+<!-- END TOKEN Autogenerated - DO NOT EDIT -->

docs/toc.json

@@ -236,6 +236,7 @@
 				]
 			},
 			{ "docs/reference-guides/richtext.md": [] },
+			{ "docs/reference-guides/theme-json-reference.md": [] },
 			{ "packages/components/README.md": "{{components}}" },
 			{ "docs/reference-guides/packages.md": "{{packages}}" },
 			{

package.json

@@ -224,8 +224,9 @@
 	},
 	"scripts": {
 		"analyze-bundles": "npm run build -- --webpack-bundle-analyzer",
-		"api-docs:ref": "node ./bin/api-docs/update-api-docs.js",
 		"api-docs:blocks": "node ./bin/api-docs/gen-block-lib-list.js",
+		"api-docs:ref": "node ./bin/api-docs/update-api-docs.js",
+		"api-docs:theme-ref": "node ./bin/api-docs/gen-theme-reference.js",
 		"clean:packages": "rimraf \"./packages/*/@(build|build-module|build-style)\"",
 		"clean:package-types": "tsc --build --clean",
 		"prebuild:packages": "npm run clean:packages && lerna run build",
@@ -312,6 +313,7 @@
 		"packages/**/*.{js,ts,tsx,json}": [
 			"npm run api-docs:ref",
 			"npm run api-docs:blocks",
+			"npm run api-docs:theme-ref",
 			"node ./bin/api-docs/are-api-docs-unstaged.js",
 			"node ./bin/packages/lint-staged-typecheck.js"
 		]

schemas/json/theme.json

@@ -10,7 +10,7 @@
 		"settingsProperties": {
 			"properties": {
 				"appearanceTools": {
-					"description": "Setting that enables ui tools.",
+					"description": "Setting that enables the following UI tools:\n\n- border: color, radius, style, width\n- color: link\n- spacing: blockGap, margin, padding\n- typography: lineHeight",
 					"type": "boolean",
 					"default": false
 				},
@@ -1041,7 +1041,7 @@
 				}
 			},
 			"patternProperties": {
-				"^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$": {
+				"^[a-z][a-z0-9-]*/[a-z][a-z0-9-]*$": {
 					"$ref": "#/definitions/stylesPropertiesAndElementsComplete"
 				}
 			},