Corey Salzano

Mimic the WordPress.org developer reference for your project

I replicated wordpress.org’s code reference system for my own project.

WordPress provides a template tag get_the_title() and it’s documented at https://developer.wordpress.org/reference/functions/get_the_title/.

A plugin I just launched provides a template tag invp_get_the_price() and it’s documented at https://inventorypresser.com/docs/reference/functions/invp_get_the_price/

I learned that the .org docs page content is generated by scanning the project source code, extracting PHPDoc comments, and parsing them into custom post types. The piece of software that does that is https://github.com/WordPress/phpdoc-parser.

Build the Data

  1. Add PHPDoc comments to all classes and methods in your plugin.
  2. Use a server that provides the WordPress Command Line Interface.
  3. Upload your plugin to the site where you want to generate documentation.
  4. Activate the phpdoc-parser plugin on the same site
  5. Connect via SSH and run a wp-cli command similar to wp parser create ../../sites/inventorypress/wp-content/plugins/inventory-presser/ --user=corey
    1. Replace the path with a path to the plugin for which you want documentation.
    2. Change the user name to the name of an administrator on your site.

Build the Theme

WordPress.org uses a handful of themes at once. The developer reference pieces live in the wporg-developer theme.

Take Files from wporg-developer

This SVN command will download the whole theme. Paste the command into a terminal or command prompt window:

svn co https://meta.svn.wordpress.org/sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/

Copy these files from wporg-developer into your child theme

  • /inc
  • /js
  • /reference
  • /stylesheets
  • content-reference.php
  • content-reference-archive.php
  • functions.php (comingle it with your functions.php)

Theme Mods

  1. Change option value wp_parser_root_import_dir to contain a path to the project. For me, this path points to a plugin in the wp-content/plugins folder.
  2. Change get_template_directory_uri() calls to get_stylesheet_directory_uri() calls
  3. Create single.php by taking a copy from the parent theme. Modify it to serve a different content template for the post types populated by phpdoc-parser. Here is a code sample that shows what to change to create a Twenty Twenty-One child theme.
  4. Optional: Change “View on Trac” links
    I added two filters that wrap the URL and the text in the “View on Trac” link below the source code section of each page. These changes allow me to change the links to “View on Github” or wherever I want.
    1. wp-parser_source_url_base line 1173 of template-tags.php
    2. wp-parser_view_on_trac_link_text in a few places in template-source.php

Twenty Twenty-One Child Theme

Download a Twenty Twenty-One child theme with the files listed and mods 1-3 completed: https://github.com/csalzano/twentytwentyone-wporg-child

Twenty Twenty Four Child Theme

In early 2024, I redesigned inventorypresser.com using a Twenty Twenty Four child theme. I followed my own instructions in this post. I’ve published the child theme for anyone to use at https://github.com/fridaysystems/exteriordoor

Also Run These Plugins

  1. Handbook By WordPress.org
  2. Handbook Functionality for Pages By Nacin
  3. SyntaxHighlighter Evolved styles the source code editors.
  4. WP Parser creates the content in the Build the Data step above.
  5. WP Parser – Deleter By me, Corey Salzano. keeps track of every post created or updated by phpdoc-parser. Deletes untouched posts and empty taxonomy terms after wp-parser runs.
  6. WP Parser – Vendor Folder Ignorer By me, Corey Salzano. Instructs phpdoc-parser to ignore the /vendor folder

Troubleshooting

Missing Source Code

If no source code is displaying, edit the option wp_parser_root_import_dir to contain a full path to the directory of the plugin. Example: /corey/sites/inventorypress/wp-content/plugins/inventory-presser

Automating Updates to Docs

When I wrote this post in 2021, the site I built this for was hosted at WP Engine. I no longer use this Github Action:

I wrote a Github Action to automate the creation and updating of the docs pages. When I push to the master branch of my plugin’s repo, the plugin is deployed to the site on WP Engine where the docs pages are hosted, and the wp-cli command that generates the docs is run.

Here is the workflow file that defines the Action at Github: https://github.com/fridaysystems/inventory-presser/blob/master/.github/workflows/main.yml

It contains one job with two steps that are marked with these comments: