Bundle documentation templates

[paulgibbs]

I've been thinking about the problem of requiring people to build templates to display the data that this importer generates. Right now, it's not ideal:

• You have to register post types / taxonomies with the specific names that the importer uses.
• While it's a post type, you have to create template file for the single posts and archive templates, etc. While WP's template hierarchy will make things work with the default single.php template etc, this is almost certainly not going to be a decent experience for something as structured as the posts we create.

We could bundle template files with the plugin and tell users to copy into their theme, but as these will be full templates, we'll quickly find people complaining that the HTML/CSS structure is different from their themes' templates, and so on.

Proposal: create a plugin that registers the post types, and use bbPress/BuddyPress theme compatibility techniques to enable an out-of-the-box documentation experience for any site.

[paulgibbs]

Sample template functions as mentioned in commit beb7630 are at https://gist.github.com/paulgibbs/5693065

[paulgibbs]

I thought about this some more. I'd suggest creating a bunch of new Git repos for different parts of this project, and using a subtree or a submodule (don't know what I'm talking about here -- I mean like an svn external) to glue them all together.

There's some distinct parts already:

• /lib/WP/* -- the WP parser and required dependencies
• The CLI exporter/importer

And I'd add:

• An WP Importer plugin to read the JSON and create the posts for hosts that don't allow SSH/WP-CLI.
• I think @rmccue likes the idea of generating the JSON/posts directly inside WordPress, so maybe a WP Exporter plugin, too. (Not convinced by this approach, but including here for completeness).
• A helper plugin to register the post types (to avoid manual changes to your theme).
• "Out of the box" templates that can be dropped into a theme for the post types.

Ideally I would like to merge the last two bullets into one plugin, like I described originally in this ticket.

[rmccue]

Ideally, what I'd like is two parts:

• The generator as a standalone utility - It should be possible to run the importer on an arbitrary system rather than just on the box that has the site. At the moment, this is the parser + WP CLI command
• A WP plugin for everything else - Importer, post type registration, templates. Not too concerned about an exporter

In practice, separating the generator out isn't going to be possible until wp-cli/wp-cli#424 is handled. In any case, IMO the plugin should include the importer, the post type registration and the templates.

So, path from where we are to where we want to end up:

• Split the CLI command into a separate file (for when we can separate the generator out more)
• Add default templates + template loader to the plugin

The template functions look good, but since we're 5.3+, let's go full namespacing. I'm thinking namespace WP-API\TemplateTags for those functions, then in a theme we can use use WP-API\TemplateTags as API and API\the_return_type()

[paulgibbs]

Putting aside the technical implementation details for now, I broadly agree, but for the record, I absolutely do not want to loose the ability to generate and import data via WP-CLI.

Over the next couple of weeks, I'll put together a bare-bones plugin with how I'm thinking the templating should work, and will then make that available for you to review.

[JDGrimes]

In practice, separating the generator out isn't going to be possible until wp-cli/wp-cli#424 is handled.

Now wp-cli/wp-cli#936

In any case, IMO the plugin should include the importer, the post type registration and the templates.

+1 for some templates.

[GaryJones]

If templates are to be included in the plugin, these should be overideable by templates in the theme. Gamajo Template Loader handles the logic needed, which just leaves a simple subclass that defines the directories used to hold the templates.

[Rarst]

On the fence about templates. For now templates tags are in the process of settling in and cleaning up. Personally I am fine with leaving templates to DIY it's up to theme.

Bundling is worth revisiting once (if :) we have several people running different sites on it and see commonalities in template needed.

[ckpicker]

Has any progress been made on this? I'd love to see some override-able templates (similar to bbPress or WooCommerce) that would allow theme devs to see how things are intended to work by default, and then customize as necessary.

[Rarst]

Not so far. Honestly I think there is still depressing amount of internal cleanup to get through (which is completely stalled) before getting to figuring out generic reuse and public APIs here.