Support Documentation

[remkus]

When released we need to have at least some basic documentation published on my.forsitethemes.com

[ryanholder]

Any idea of what basic documentation we should have ?

I can think of things like;

• Using class names for social icons
• A page that displays the current icons and their class names

[remkus]

• Explanation of the FortyTwo Structure
  • in terms of CSS
  • in terms of LESS
  • in terms of Folders
  • in terms of Functions
• Post Info & Post Meta tutorials (same as StudioPress has basically, but better) since we're using those
• Explanation of Widgets + Tutorials (would actually like to have Screencasts and such)
• Explanation of Bootstrap (briefly) + linking to how to expand it
• How to extend FortyTwo
  • CSS
  • Functions

Stuff like this.

[ryanholder]

That all sounds like valuable info to me, should we create a site plan here ?

[GaryJones]

In addition to documentation for users, how about a WP-Parser generation import too, such like there now is (first version) on https://developer.wordpress.org/reference?

[remkus]

I’d actually like that. Are there solutions we can use that create HTML as output?

[GaryJones]

Are there solutions we can use that create HTML as output?

There's this little known tool called WordPress... ;-)

WP-Parser runs via WP-CLI over .php files in a project (WP Core, Genesis, a child theme, a plugin, whatever) and pulls all of the documentation data into a .json file.

The WP-Parser plugin also includes registering post types for functions, methods, classes and hooks.

It also includes an importer which takes that .json file and creates relevant post type entries as needed, and dumps a whole load into post meta data. You can then use WP to show as you would any other CPT content, styling with a theme as per usual. @since and @package are sets as tags, allowing to easily jump to see what's new in a particular version, for example.

Importing an import file after re-parsing a project only updates what's necessary - it shouldn't create duplicate entries etc.

The current state of WP-Parser is that it works, could be tightened up more, and once done, could be split into separate plugins - one that registers the post types, one that does the parsing, and one that does the importing, since they are very different focus areas.

[remkus]

This WP Parser? Because if that turns the documentation into a site like developer.wordpress.org we can easily use that on subdomain. FYI: forsitethemes.com is a multi-site with my.forsitethemes.com as currently the only sub-site.

[GaryJones]

Yes, that's the project I'm referring too. Rarst is leading the project, although it's still under Ryan McCues account at the moment.

Although the focus is on using WP-Parser for the .org reference (and so takes priority), Rarst is definitely of the mindset that WP-Parser is for parsing all WordPress projects to pull out documentation, and displaying it within a WP-backed site. I did an early run against Genesis, and even using Sample theme, it's clear it could be very useful.

If you look under Rarst's account, there should be a wporg-developer theme project as well. Not looked into it, but that would should how to pull the post meta (though it's all standard), apply syntax highlighting etc. Could obviously start with that and fork from there if necessary.

[GaryJones]

Notes to future self - grunt shell locally can't be used, as it needs to run wp parser command, and although WP-CLI exists, the parser command doesn't exist until WP-Parser plugin is installed and active on a local site.

Also, as we're now using the placeholder for versions, this needs to run after the replace:release task has been run (even if nothing is committed) to ensure we're not left with @@release throughout the export.

Under vagrant ssh, wp parser export . will put a phpdoc.json export into the theme root if run from the theme root.

[GaryJones]

http://pastebin.com/raw.php?i=72Y84acJ is a raw output, so you can use WP-Parser to import it into a docs WP install and start doing a theme that shows it all off.

Doing a fresh export, and importing that won't create duplicate entries, so it can be repeated when necessary.