Export method code snippets

[adamziel]

Exploration work in progress. @sirreal, could you take a look when you have a chance?

What it does

Exports runnable PHP examples from DocBlocks as doc.code_snippets, strips those snippet fences from doc.long_description, and stores the snippet metadata during import.

A DocBlock can pair a php fence with expected-output and optional setup Blueprint data:

```php
<?php
echo 'Hello';
```

```expected-output
Hello
```

For reusable setup, define a named setup Blueprint once and reference it from multiple PHP fences:

```setupblueprint shared-greeting
{"steps":[{"step":"writeFile","path":"/wordpress/wp-content/mu-plugins/shared.php","data":"<?php ..."}]}
```

```php blueprint=shared-greeting
<?php
require '/wordpress/wp-load.php';
echo docs_shared_greeting( 'first' );
```

```php setup-blueprint=shared-greeting
<?php
require '/wordpress/wp-load.php';
echo docs_shared_greeting( 'second' );
```

File-level setup Blueprints are inherited by functions, classes, and methods in that file, so one setup definition can be reused by several examples.

Screenshot

Actual wporg-developer render from an imported fixture using this parser branch plus WordPress/wporg-developer#567. The second and third examples share a named setup Blueprint.

Rationale

WordPress.org docs need structured data for php-code-snippet, with JSON as the intermediate format. Exporting code, expected_output, and setup Blueprint data avoids reverse-parsing rendered HTML later.

Stripping snippet fences from long_description keeps the theme from rendering duplicate examples: the plain code fence disappears and the runnable snippet becomes the representation of that example.

Implementation

export_docblock() is now the single path for snippet extraction. It:

• exports code_snippets for PHP fences
• exports setup_blueprints for named setup definitions
• inherits referenced setup Blueprints from file/class DocBlocks
• strips snippet, expected-output, and Blueprint fences from long_description

WPORG_Parser\Importer stores the arrays as _wp-parser_code_snippets and _wp-parser_setup_blueprints post meta so themes can render them after import.

The parser is intentionally narrow:

• exports php fences only; other fences are metadata or ignored
• supports 3+ backtick fences with matching open/close lengths
• supports indented fences and strips matching fence indentation from contents
• allows different-length fences inside snippets
• attaches inline blueprint, setup-blueprint, and json blueprint fences to nearby PHP snippets
• exports named setupblueprint, setup-blueprint, and json setupblueprint fences once under setup_blueprints
• lets PHP fences reference named setup with blueprint=<name>, setup-blueprint=<name>, or setupblueprint=<name>
• treats expected-output as the end of the following-metadata run so later setup data can belong to the next snippet
• ignores incomplete snippets after an unterminated fence

This is not a full Markdown parser; it extracts the DocBlock fence shapes needed for JSON export.

Testing instructions

Run:

php -l lib/runner.php lib/class-importer.php tests/phpunit/tests/export/docblocks.php tests/phpunit/tests/export/docblocks.inc
git diff --check
php .context/check-snippets.php
php .context/check-named-setup.php
php .context/check-strip-inherited.php

The tests cover snippets with no metadata, expected output, inline Blueprints before and after PHP, reusable named setup Blueprints, file-level setup Blueprints inherited by methods, multiple snippets sharing the same setup, string Blueprint fallback, case-insensitive fence names, info strings, non-PHP fences, exact fence lengths, different-length fences inside snippets, text after would-be closers, indented fences, metadata boundaries, description stripping, and unterminated fences.