Update docs for the step "importThemeStarterContent"

[bph]

The documentation lists a step: "importThemeStarterContent"
Implementation issue shows, that it's an option on the InstallTheme step.

It's already included in the installTheme step. documentation

Example quoted from the PR:

{
  "steps": [
    {
      "step":"installTheme",
      "themeZipFile":{
        "resource":"wordpress.org/themes",
        "slug":"twentytwenty"
       },
       "options":{
         "importStarterContent": true
       }
    }
  ]
}

[bph]

There are two files:

• packages/playground/blueprints/src/lib/steps/import-theme-starter-content.ts
• packages/playground/blueprints/src/lib/steps/import-theme-starter-content.spec.ts

I can't figure out where to make the updates to remove the step from the documentation, though.

[bph]

And maybe it shouldn't be under steps at all but added to the InstallTheme step..

I see in import-theme-starter-content.ts

/**
 * @inheritDoc importThemeStarterContent
 * @example
 *
 * <code>
 * {
 * 		"step": "importThemeStarterContent"
 * }
 * </code>
 */

and further down

	step: 'importThemeStarterContent';
	/**
	 * The name of the theme to import content from.
	 */
	themeSlug?: string;
}

/**
 * Imports a theme Starter Content into WordPress.
 *
 * @param playground Playground client.
 */

Should that be all that needs to be deleted?

[bgrgicak]

@bph importThemeStarterContent is both a step and an option in the installTheme step. Why would you like to remove the step?

It's nice to have both in case you need to do something more custom. For example, you can install a theme that doesn't have starter content, add it using a writeFile step, and run importThemeStarterContent later.

[bgrgicak]

There are two files:

* packages/playground/blueprints/src/lib/steps/import-theme-starter-content.ts

* packages/playground/blueprints/src/lib/steps/import-theme-starter-content.spec.ts

I can't figure out where to make the updates to remove the step from the documentation, though.

You would update the import-theme-starter-content.ts file to make documentation example changes. The /import-theme-starter-content.spec.ts file only contains unit tests that automatically check if the step works.

[bgrgicak]

To answer your question about deleting steps.

Check if the step is used

We collect step usage stats in Google Analytics, so before we remove anything, we can check how frequently it is used. The importThemeStarterContent step is rarely used.

Before we can remove it, we usually mark it as deprecated for a while before actually removing it.

Deleting a step

To delete a step you need to delete the step interface, in this case, it would be this code:

wordpress-playground/packages/playground/blueprints/src/lib/steps/import-theme-starter-content.ts

Lines 4 to 21 in f677792

	/**
	* @inheritDoc importThemeStarterContent
	* @example
	*
	* <code>
	* {
	* "step": "importThemeStarterContent"
	* }
	* </code>
	*/
	export interface ImportThemeStarterContentStep {
	/** The step identifier. */
	step: 'importThemeStarterContent';
	/**
	* The name of the theme to import content from.
	*/
	themeSlug?: string;
	}

You also need to delete any references to the interface by searching the Playground project for its name (i.e. ImportThemeStarterContentStep).

Finally, you need to remove the step from the blueprint schema, in this case, it would be this code:

wordpress-playground/packages/playground/blueprints/public/blueprint-schema.json

Lines 556 to 583 in 07fb8ba

	{
	"type": "object",
	"additionalProperties": false,
	"properties": {
	"progress": {
	"type": "object",
	"properties": {
	"weight": {
	"type": "number"
	},
	"caption": {
	"type": "string"
	}
	},
	"additionalProperties": false
	},
	"step": {
	"type": "string",
	"const": "importThemeStarterContent",
	"description": "The step identifier."
	},
	"themeSlug": {
	"type": "string",
	"description": "The name of the theme to import content from."
	}
	},
	"required": ["step"]
	},

[bph]

Thank you, @bgrgicak
Ah sorry, this wasn't clear. For this issue, I was only thinking of removing the step from the Documentation, not so much from Playground.

This PR #1521 was the only one I found about this, and it only mentions the installTheme option, unless I am missing something. There is also no example on how to use the step variation. My conclusion was that the documentation wasn't updated, and we can take care of it by removing it from the Documentation. Only when I tried to find the spot where the documentation originated, I found the step files, and was confused.

Before we can remove it, we usually mark it as deprecated for a while before actually removing it.

This was a misunderstanding, and I would love to update the documentation with a working example for the step variation on how to do this in a blueprint. The current version doesn't help here much. Or I don't understand it.

For example, you can install a theme that doesn't have starter content, add it using a writeFile step, and run importThemeStarterContent later.

That's a great use case. How would this be accomplished via blueprint?

[bgrgicak]

The current version doesn't help here much. Or I don't understand it.

I agree, some of our Blueprint examples are so minimal that they don't do anything on their own or even break the site.

[bgrgicak]

That's a great use case. How would this be accomplished via blueprint?

Here is a minimal example which adds a new homepage section.

[bph]

I replicated your example slightly different content for the blueprint gallery.
WordPress/blueprints#82

Now I can update the documentation with something like

@example 
  *  add the function  add_theme_support( 'starter-content', array( /*...*/ ) )  to a plugin file via the writeFile steps, 
  * activate the plugin and then use the step. [See example in Blueprint Gallery](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/WordPress/blueprints/filestartercontent/blueprints/filestartercontent/blueprint.json) 
  * <code> 
  * { 
  * 		"step": "importThemeStarterContent" 
  * } 
  * </code> 
  */ 

any other thoughts on how to update the documentation section?

[bph]

Could also add a link to the Dev Note on Make Core: Starter content for themes in 4.7

[adamziel]

@bph I love the idea of improving the documentation for that step. At the same time linking to the Blueprints Gallery is less useful than including the example and the writeup inline in the docstring. It's fine if it's a copy&pasted example and it takes 50 or 100 lines of comment as long as it's immediately available inline. WDYT?

[adamziel]

@bph would you be interested in adjusting the docstring @bgrgicak linked to in his comment once you're back from the new year's AFK?

[bph]

@adamziel I would agree.

Here is the full blueprint from @bgrgicak example:

  "steps": [
    {
      "step": "writeFile",
      "path": "/wordpress/wp-content/plugins/theme-starter-content.php",
      "data": {
        "resource": "url",
        "url": "**https://gist.githubusercontent.com/bgrgicak/6ad8ea2da1e2e79d523ce80c8ae0f98c/raw/3f192b458ffcbde5d21b005ccb501082f41d8efb/theme-starter-content.php**"
      }
    },
    {
      "step": "activatePlugin",
      "pluginPath": "/wordpress/wp-content/plugins/theme-starter-content.php"
    },
    {
      "step": "importThemeStarterContent"
    }
  ]
}

linking to the Blueprints Gallery is less useful than including the example and the writeup inline in the docstring.

I don't know if linking to a personal Gist is so much better than linking to the blueprints gallery example....