Regenerate reference for 5.4

README.md

@@ -7,3 +7,13 @@ This repo contains the source for [documentation for the API](https://developer.
 When creating new files, these must be added to the manifest. Run `bin/generate-manifest.php` to update this.
 
 Removing files also requires regenerating the manifest. After deletion and sync with DevHub, the page also needs to be manually deleted from DevHub.
+
+## Refreshing the Templated API Reference
+
+The reference section is created by parsing the output of a site's schema as retrieved from that site's REST API index route. The current method used to generate this approach is as follows:
+
+- Create a local WordPress environment (always use the current or Release Candidate version of WordPress) using the local environment tool of your choice.
+- Edit `/etc/hosts` to map the domain `example.com` to the IP of that WordPress instance, and ensure the site is configured to run at `example.com`.
+- Run `composer install` in this project's root directory to install dependencies. 
+- Run `composer run-script regenerate` in this project's root directory to run the asset regeneration script.
+- Use `git status` and `git diff` to validate that the files were updated as expected.

bin/manifest.json

@@ -64,6 +64,16 @@
  "parent": "extending-the-rest-api",
  "markdown_source": "https://github.com/WP-API/docs/blob/master/extending-the-rest-api/schema.md"
  },
+ "reference/block-revisions": {
+ "slug": "block-revisions",
+ "parent": "reference",
+ "markdown_source": "https://github.com/WP-API/docs/blob/master/reference/block-revisions.md"
+ },
+ "reference/blocks": {
+ "slug": "blocks",
+ "parent": "reference",
+ "markdown_source": "https://github.com/WP-API/docs/blob/master/reference/blocks.md"
+ },
  "reference/categories": {
  "slug": "categories",
  "parent": "reference",
@@ -144,16 +154,6 @@
  "parent": "reference",
  "markdown_source": "https://github.com/WP-API/docs/blob/master/reference/users.md"
  },
- "reference/wp_block-revisions": {
- "slug": "wp_block-revisions",
- "parent": "reference",
- "markdown_source": "https://github.com/WP-API/docs/blob/master/reference/wp_block-revisions.md"
- },
- "reference/wp_blocks": {
- "slug": "wp_blocks",
- "parent": "reference",
- "markdown_source": "https://github.com/WP-API/docs/blob/master/reference/wp_blocks.md"
- },
  "using-the-rest-api/authentication": {
  "slug": "authentication",
  "parent": "using-the-rest-api",

bin/regenerate.php

@@ -1,8 +1,18 @@
 #!/usr/bin/env php
 <?php
 
+namespace WPAPI\Docs\Regenerate;
+
+use Requests;
+use Twig;
+
 require dirname( __DIR__ ) . '/vendor/autoload.php';
 
+// This assumes you have a local WP VM running the latest stable WP, mapped to
+// use the domain name example.com using /etc/hosts. http://demo.wp-api.org is
+// also available, though may be outdated.
+const SITE_URL = 'http://example.com';
+
 function update_route( $route ) {
 foreach ( $route['endpoints'] as &$endpoint ) {
 if ( in_array( 'POST', $endpoint['methods'] ) ) {
@@ -23,10 +33,18 @@ function update_route( $route ) {
 return $route;
 }
 
+/**
+ * Ingest a title string and ensure any kebab-casing or wp_-prefixing is removed.
+ */
+function cleanup_name( string $name ) : string {
+return preg_replace( '/WP_/i', '', implode( ' ', explode( '-', $name ) ) );
+}
+
 function add_simple_schemas() {
 $objects = [];
 
-$response = Requests::get( 'http://demo.wp-api.org/wp-json/?context=help' );
+$response = Requests::get( SITE_URL . '?rest_route=/&context=help' );
+
 $parsed_data = json_decode( $response->body, true );
 
 foreach ( $parsed_data['routes'] as $key => $route ) {
@@ -56,6 +74,18 @@ function add_simple_schemas() {
 $title = 'Media Item';
 $plural = 'media';
 break;
+
+case 'rendered-block':
+$key = 'rendered-blocks';
+$title = 'Rendered Block';
+$plural = 'Rendered Blocks';
+break;
+
+case 'settings':
+$key = 'settings';
+$title = 'Site Setting';
+$plural = 'Site Settings';
+break;
 
 case 'status':
 $plural = 'statuses';
@@ -65,11 +95,28 @@ function add_simple_schemas() {
 case 'type':
 $key = 'post-types';
 break;
+
+case 'wp_block':
+$key = 'blocks';
+$title = 'Editor Block';
+$plural = 'Editor Blocks';
+break;
+
+case 'wp_block-revision':
+$key = 'block-revisions';
+$title = 'Block Revision';
+$plural = 'Block Revisions';
+break;
+
+default:
+// Fallback title cleaning logic, to remove kebab-casing, etcetera.
+$title = cleanup_name( $title );
+$plural = cleanup_name( $plural );
 }
 
 if ( ! isset( $objects[ $key ] ) ) {
 $objects[ $key ] = [
-'name' => $title,
+'name'  => $title,
 'plural' => $plural,
 'routes' => [ $route_nicename => update_route( $route ) ],
 'schema' => $route['schema'],
@@ -83,7 +130,7 @@ function add_simple_schemas() {
 }
 
 function add_terms_schema() {
-$response = Requests::options( 'http://demo.wp-api.org/wp-json/wp/v2/terms/category' );
+$response = Requests::options( SITE_URL . '?rest_route=/wp/v2/terms/category' );
 $file = fopen( '_data/terms.json', 'w' );
 $parsed_data = json_decode( $response->body );
 
@@ -98,12 +145,11 @@ function twig() {
 return $twig;
 }
 
-$loader = new Twig_Loader_Filesystem( __DIR__ . '/templates' );
+$loader = new Twig\Loader\FilesystemLoader( __DIR__ . '/templates' );
 
-$twig = new Twig_Environment( $loader, array(
+$twig = new Twig\Environment( $loader, [
  'cache' => false,
- // 'cache' => __DIR__ . '/cache',
-) );
+] );
 return $twig;
 }
 

bin/templates/endpoint.md

@@ -1,17 +1,12 @@
 ---
 ---
 
-# {{ plural | capitalize }}
+# {{ plural | title }}
 
 <section class="route">
 <div class="primary">
 {{ include('reference-parts/schema.html') }}
 </div>
-<div class="secondary">
-<h3>Example Request</h3>
-
-<code>$ curl -X OPTIONS -i https://example.com/wp-json{{ attribute( routes | first, 'nicename' ) }}</code>
-</div>
 </section>
 
 <div>

bin/templates/reference-parts/create-item.html

@@ -1,6 +1,6 @@
 <section class="route">
 <div class="primary">
-<h2>Create a {{ name | capitalize }}</h2>
+<h2>Create a {{ name | title }}</h2>
 {{ include( 'reference-parts/args-list.html', { args: endpoint.args, link: true } ) }}
 </div>
 <div class="secondary">

bin/templates/reference-parts/delete-item.html

@@ -1,6 +1,6 @@
 <section class="route">
 <div class="primary">
-<h2>Delete a {{ name | capitalize }}</h2>
+<h2>Delete a {{ name | title }}</h2>
 {{ include( 'reference-parts/args-list.html', { args: endpoint.args } ) }}
 </div>
 <div class="secondary">

bin/templates/reference-parts/get-item.html

@@ -1,15 +1,16 @@
 <section class="route">
 <div class="primary">
-<h2>Retrieve a {{ name | capitalize }}</h2>
-{{ include( 'reference-parts/args-list.html', { args: endpoint.args, link: false } ) }}
-</div>
-<div class="secondary">
-<h3>Definition</h3>
+<h2>Retrieve a {{ name | title }}</h2>
+
+<h3>Definition & Example Request</h3>
 
 <code>GET {{ route.nicename }}</code>
 
-<h3>Example Request</h3>
+<p>Query this endpoint to retrieve a specific {{ name }} record.</p>
 
 <code>$ curl https://example.com/wp-json{{ route.nicename }}</code>
 </div>
+<div class="secondary">
+{{ include( 'reference-parts/args-list.html', { args: endpoint.args, link: false } ) }}
+</div>
 </section>

bin/templates/reference-parts/list-item.html

@@ -1,9 +1,8 @@
 <section class="route">
 <div class="primary">
-<h2>List {{ plural | capitalize }}</h2>
-{{ include( 'reference-parts/args-list.html', { args: endpoint.args, link: false } ) }}
-</div>
-<div class="secondary">
+<h2>List {{ plural | title }}</h2>
+<p>Query this endpoint to retrieve a collection of {{ plural }}. The response you receive can be controlled and filtered using the URL query parameters below.</p>
+
 <h3>Definition</h3>
 
 <code>GET {{ route.nicename }}</code>
@@ -12,4 +11,7 @@ <h3>Example Request</h3>
 
 <code>$ curl https://example.com/wp-json{{ route.nicename }}</code>
 </div>
+<div class="secondary">
+{{ include( 'reference-parts/args-list.html', { args: endpoint.args, link: false } ) }}
+</div>
 </section>

bin/templates/reference-parts/schema.html

@@ -1,5 +1,5 @@
 <h2>Schema</h2>
-<p>The schema defines all the fields that exist for a {{ schema.title }} object.</p>
+<p>The schema defines all the fields that exist within a {{ name }} record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.</p>
 <table class="attributes">
 {% for key, property in schema.properties %}
 <tr id="schema-{{ key }}">

bin/templates/reference-parts/update-item.html

@@ -1,6 +1,6 @@
 <section class="route">
 <div class="primary">
-<h2>Update a {{ name | capitalize }}</h2>
+<h2>Update a {{ name | title }}</h2>
 {{ include( 'reference-parts/args-list.html', { args: endpoint.args, link: true } ) }}
 </div>
 <div class="secondary">

composer.json

@@ -1,6 +1,11 @@
 {
+ "name": "wp-api/docs",
+ "description": "The WordPress REST API Handbook",
  "require": {
  "rmccue/requests": "^1.7",
- "twig/twig": "~1.0"
+ "twig/twig": "^3.0"
+ },
+ "scripts": {
+ "regenerate": "php bin/regenerate.php"
  }
 }