Download the PHP package gebruederheitz/wp-theme-docs without Composer

Wordpress Theme Admin Page and Documentation Maker

Add simply admin pages or a Wordpress theme documentation page to the editor.

Installation

via composer:

Make sure you have Composer autoload or an alternative class loader present.

Usage

This will set up a basic admin page under the "Tools" tab in the Wordpress backend with the translated title __('Extra Tools', 'ghwp') (/wordpress/wp-admin/tools.php?page=my-extra-admin-page).

In its most basic state, this renders a page empty except for the title. You will need to register sections to add some content.

Constructor (and factory) arguments

Adding sections

Section registration & custom sections

Any section you add must implement the AdminPageSectionInterface. You can use the method addSection() or the filter hook to add your section to a page:

using addSection()

using the hook

For convenience, you can extend the AbstractAdminPageSection, which already has the interface implemented, only requiring you to implement three abstract getters to get it to run.

The above example sets up a section with the title Documentation for my amazing feature rendering from the template partial at the given path. The template is passed the instance of AdminPage and the current section:

Instead of setting the $partial property (or even extending the abstract class), you can also implement a custom rendering method:

The theme documentation page

This will set up the basic documentation page under the "Appearance" tab in the Wordpress backend with the translated title __('Theme-Help', 'ghwp') (/wordpress/wp-admin/themes.php?page=ghwp-help).

It's simply a preconfigured AdminPage, so you will need to add sections. In this case, you can add them right through the constructor by passing an array as the first argument:

Warning

Due to how PHP inheritance works, AdminPage's static ::factory() method is available on DocumentationMenu, but it should not be used, as it will return a simple AdminPage object, not a DocumentationMenu instance.

DocumentationMenu: Changing the title and the template used

You can change the title displayed on the documentation page by passing a string as the constructor's second argument:

You can override the default template by creating a file in your theme's root directory under template-parts/meta/docs/documentation-page.php.

Alternatively you may override this default path by supplying a second argument to the constructor:

Included sections

The sections included in this package all extend AbstractAdminPageSection.

This will register the sections and add them to the help page.

Shortcode Documentation Annotations

This module will automatically create a shortcode documentation for users based on the annotation class ShortcodeDocumentation. It is based on Doctrine's annotation reader.

Documenting shortcodes

This assumes you add your shortcodes via individual classes for each shortcode and have both the DocumentationMenu page class and the Shortcodes section class up and running.

Available annotation properties:

The simplest way to document your Shortcode is to use the trait provided:

Alternatively, you can register your annotation yourself:

Changing the template partial for the section

As with all section classes extending AbstractAdminPageSection, you have two options of modifying the default output:

Using the default override template

Create a file in your theme's root directory under template-parts/meta/docs/shortcodes.php. This template will be used instead of the provided default.

The section template will be called with two arguments: an instance each of DocumentationMenu and the section (Shortcodes):

Using a different template partial location

You'll need to extend the Shortcodes class and provide an alternative getter:

List of SVG icon partials

This module will render a list of all icons that can be used by editors (for instance via shortcodes). By default it searches template-parts/svg/ in your theme's root directory recursively for .php files, assuming they are templates containing SVG markup.

This is most useful in conjunction with a shortcode that can render these SVG partials, for instance into button blocks.

Setting a different path for SVG partials

Same as with the Shortcodes section.

Development

Dependencies

• PHP >= 7.4
• Composer 2.x
• NVM and nodeJS LTS (v16.x)
• Nice to have: GNU Make (or drop-in alternative)

Migration

v1 to v2

• The PSR-4 namespaces changed; so instead of using Gebruederheitz\Wordpress\Documentation\DocumentationPage you will need to use Gebruederheitz\Wordpress\AdminPage\Documentation\DocumentationPage etc.
• AdminPageSectionInterface replaces DocumentationSectionInterface, AbstractAdminPageSections replaces AbstractDocumentationSection.
• For a complete list of namespace and class name changes refer to the table below.
• Sections do not extend Singleton anymore, so you will have to construct them like any regular class instead of calling ::getInstance().
• The filter hook for documentation sections has changed from ghwp_filter_documentation_sections to ghwp_filter_sections_ghwp-help. You can not use DocumentationPage::HOOK_SECTIONS anymore; either use the literal hook name, get the name via $documentationPageInstance->getSectionsHook(), or (preferred) use $documentationPageInstance->addSection(AdminPageSectionInterface