Doc: Add documentation for ancestor property in block metadata (#40027

)

* Add documentation for `ancestor` property

Adds documentation for the new API added in #39894

* Update docs/reference-guides/block-api/block-metadata.md

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>

* Add ancestors example in innerblocks tutorial

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
Co-authored-by: Luis Herranz <luisherranz@gmail.com>

docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md

@@ -155,18 +155,30 @@ add_action( 'init', function() {
 } );
 ```
 
-## Parent-Child InnerBlocks
+## Child InnerBlocks: Parent and Ancestors
 
-A common pattern for using InnerBlocks is to create a custom block that will be included only in the InnerBlocks. An example of this is the Columns block, that creates a single parent block called `columns` and then creates an child block called `column`. The parent block is defined to only allow the child blocks. See [Column code for reference](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src/column).
+A common pattern for using InnerBlocks is to create a custom block that will be included only in the InnerBlocks. 
+
+An example of this is the Columns block, that creates a single parent block called `columns` and then creates an child block called `column`. The parent block is defined to only allow the child blocks. See [Column code for reference](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src/column).
 
 When defining a child block, use the `parent` block setting to define which block is the parent. This prevents the block showing in the inserter outside of the InnerBlock it is defined for.
 
-```js
-export const settings = {
-	title: __( 'Column' ),
-	parent: [ 'core/columns' ],
-	icon,
-	description: __( 'A single column within a columns block.' ),
-	//...
-};
+```json
+{
+	"title": "Column",
+	"name": "core/column",
+	"parent": [ "core/columns" ],
+	// ...
+}
+```
+
+Another example is using the `ancestors` block setting to define a block that must be present as an ancestor, but it doesn't need to be the direct parent (like with `parent`). This prevents the block from showing in the inserter if the ancestor is not in the tree, but other blocks can be added in between, like a Columns or Group block. See [Comment Author Name code for reference](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src/comment-author-name).
+
+```json
+{
+	"title": "Comment Author Name",
+	"name": "core/comment-author-name",
+	"ancestor": [ "core/comment-template" ],
+	// ...
+}
 ```

docs/reference-guides/block-api/block-metadata.md

@@ -215,6 +215,20 @@ An implementation should expect and tolerate unknown categories, providing some
 
 Setting `parent` lets a block require that it is only available when nested within the specified blocks. For example, you might want to allow an 'Add to Cart' block to only be available within a 'Product' block.
 
+### Ancestor
+
+-   Type: `string[]`
+-   Optional
+-   Localized: No
+-   Property: `ancestor`
+-   Since: `WordPress 6.0.0`
+
+```json
+{ "ancestor": [ "my-block/product" ] }
+```
+
+The `ancestor` property makes a block available inside the specified block types at any position of the ancestor block subtree. That allows, for example, to place a ‘Comment Content’ block inside a ‘Column’ block, as long as ‘Column’ is somewhere within a ‘Comment Template’ block. In comparrison to the `parent` property blocks that specify their `ancestor` can be placed anywhere in the subtree whilst blocks with a specified `parent` need to be direct children.
+
 ### Icon
 
 -   Type: `string`