WordPress, WP Parser and Good Habits can help make your codebase easier to maintain and update – in this post I’ll go over my local setup and how this could transition into an ongoing, automated task when working a codebase for WordPress.
Documentation is often the first thing to go when working on a codebase. Either it’s forgotten about entirely or incomplete to the point where it’s literally just taking up lines of space on the screen with no real purpose.
Have you ever seen something like this in a codebase you’re working on?
/**
* Update something after processing input.
*
* @param $id
* @param $filter
*
* @return string
*/
From this above DocBlock, I may know that this function does some processing and updating but what exactly are we taking as input? An id and a filter, but what types of data do we expect here and what do these associate to?
Quickly scanning through code, having helpful information can speed up any transitioning developers on the project and also help future you to remember what that function was meant to do, six months from now.
Bringing the Documentation to the Foreground
Accessible documentation is not just a nice-to-have, it is a necessity, and WordPress has a great resource for developers with the WordPress Code Reference. But what about your own codebases? We extend and customize WordPress daily and it would be extremely useful to have our own customizable code reference. Better yet, it would be great if we didn’t need to maintain this in two places, only updating our code which would then populate the code reference automatically.
The ability to have this currently exists! Enter the WP Parser plugin, WP-CLI, and wporg-developer theme.
With these three tools, you can get up and running with your own custom Code Reference site in no time. Additionally, we can customize our workflow to help automate the process of keeping the Code Reference up to date with the codebase so that maintainability only needs to be done on the coding level. I will handle this using a custom Gulp task runner on my local environment.
This workflow is going to assume that the source site is a different build than the Code Reference site and that these both exist in the same filesystem. In fact, the way that certain features work, like the source code view on the wporg-developer theme, is that the file system needs to be accessible to pull in the data. I wanted to keep both sites separate to avoid having code reference specific post types and taxonomies on my source build.
Tools we’ll be using:
- Varying Vagrant Vagrants
- WP-CLI
- Composer
- Gulp with some additional node modules.
- WordPress Parser plugin
- wporg-developer theme
Set up the Code Reference site
Running a standard site setup with VVV, get the site going. Once that’s done, you’ll want to install the WP Parser plugin. This is most easily done by cloning it into the plugin directory on the new code reference site, then grabbing all the dependencies using the composer and activate the plugin.
pwd
/Users/Jason/Sites/vvv-machine/www/code-reference/htdocs/wp-content/plugins
git clone git@github.com:WordPress/phpdoc-parser.git
cd phpdoc-parser
composer install
Loading composer repositories with package information
Installing dependencies (including require-dev) from lock file
- Installing composer/installers (v1.1.0)
Loading from cache
- Installing erusev/parsedown (1.6.0)
Loading from cache
- Installing psr/log (1.0.0)
Loading from cache
[... omitted ...]
SSH into Vagrant and activate the plugin via wp-cli. You can do this normally too, but you will still want to make sure that the new wp-cli command for wp parser is available.
pwd
/srv/www/code-reference
wp plugin activate phpdoc-parser
Success: Plugin 'phpdoc-parser' activated.
wp parser
usage: wp parser create <directory> [--quick] [--import-internal] [--user]
or: wp parser export <directory> [<output_file>]
or: wp parser import <file> [--quick] [--import-internal]
See 'wp help parser <command>' for more information on a specific command.
Your site is now able to utilize the WP Parser. To display the code reference in a useful way, that’s where the wporg-developer theme comes in. This is a good place to start even though there are areas that need to be slightly tweaked, like the link to trac for the source code.
To set this up it’s a quick svn pull down into the theme directory and some modification to the theme files and wp-config.
pwd
/Users/Jason/Sites/vvv-machine/www/code-reference/htdocs/wp-content/themes
svn checkout https://meta.svn.wordpress.org/sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/ wporg-developer
A wporg-developer/inc
A wporg-developer/inc/jetpack.php
A wporg-developer/inc/redirects.php
[... omitted ...]
A wporg-developer/languages/wporg-developer.pot
A wporg-developer/languages/readme.txt
A wporg-developer/single.php
Checked out revision 4382.
Next up, you’ll need to modify the header, footer and wp-config on your build (assuming you are using the theme above). You can follow these steps here, but to summarize.
- Download WordPress.org header and place in the wp-content/themes directory. Add
<?php wp_head(); ?>to the end of the file. - Change the opening
<body>to<body id="wordpress-org" <?php body_class(); ?>> - Download WordPress.org footer and place in the wp-content/themes directory. Add
<?php wp_footer(); ?>directly before the closing</body> - In wp-config.php, add
define( 'WPORGPATH', __DIR__ . '/wp-content/themes/' );prior to the line/* That's all, stop editing! Happy blogging. */.
Activate that theme and you are now ready to import and view functions, classes, hooks, and methods along with the source code of your choosing. You are by no means limited to using this theme but it is a quick setup if you want to get started. One final thing you may want is the syntax highlighting plugin, SyntaxHighlighter Evolved, that the official WordPress Code Reference uses, otherwise you will have not-as-pretty source code in the theme.
With Syntax Highlighting
Without Syntax Highlighting
Source Site Gulp Workflow
By avoiding the installation of the WP Parser plugin on the source site, we don’t have to worry about cluttering up the codebase with external code. I’ve written a simple Gulp script to assist in running the parser from the Code Reference site, inside of the Vagrant box using WP-CLI. You can view the script here. This was just a quick script that I’m sure could be improved.
Now, whenever you run your gulp task, the script will SSH into the vagrant machine, execute the wp parser cli command from the code reference site on whatever path you’ve given it and import the resulting JSON into the code reference WordPress site.
You will need to install the ssh2 node module for the above script to work properly.
Gotchas and Improvements
As noted above, the theme could use some tweaking, including the way the source code gets pulled in. If any function, which was previously pulled in, changes, the source code will not update. The source code file also needs to be accessible from the Code Reference site to be pulled in.
I think this is a very good first step toward keeping a ‘style guide’ documentation of sorts for back-end code.