Docs: Add automated theme.json reference documentation (#37569)

* Initial script to generate settings and style for theme.json

* Add to table of contents and link to how to guide

- Adds a brief paragraph at top of reference guide linking to how to
  guide for examples

- Adds reference guide to table of contents / manifest

* Add markdownDescription for appearanceTools

To enrich the automated docs this adds a markdownDescription
field for appearanceTools to explain what tools are enabled.

You can see the markdownDescription field used in the tsconfig
schema here: http:https://json.schemastore.org/tsconfig

* Add support for markdownDescription in generated docs

* Update generated docs.

* Dont use markdownDescription yet, move rich description to description field.

* Remove markdownDescription field

* Change doc scripts trigger for pre-commit

Update lint-staged to command to run script to generate
theme.json reference prior to checking for changed files.

For details fixing similar issue see PR #37613

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

@@ -557,6 +557,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

@@ -221,6 +221,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"
  }
  },