PHP code example of gebruederheitz / wp-theme-docs

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

gebruederheitz / wp-theme-docs example snippets

# functions.php (or controller class)
use Gebruederheitz\Wordpress\Documentation\AdminPage;

new AdminPage('my-extra-admin-page', 'Extra Tools', 'tools.php');
// or use the factory method
AdminPage::factory('my-extra-admin-page', 'Extra Tools', 'tools.php');

AdminPage::__construct(
     string $menuSlug,
     ?string $title = null,
     ?string $menuLocation = 'themes.php',
     ?string $menuTitle = null,
     ?string $overridePath = null,
     ?string $i18nNamespace = 'ghwp'
 ): AdminPage

use Gebruederheitz\Wordpress\Documentation\AdminPage ;
$page = new AdminPage('extras');
$page->addSection(new MySection());

// Using AdminPage's factory method:
AdminPage::factory('extras')->addSection($mySection);

// Adding multiple sections with addSection() or addSections()
AdminPage::factory('extras')
    ->addSection($mySection)
    ->addSection($otherSection);
AdminPage::factory('extras')
    ->addSections([
        new MySection(),
        new OtherSection(),
    ]);

use Gebruederheitz\Wordpress\Documentation\AdminPage ;
$page = new AdminPage('extras');

function ghwp_add_doc_section(array $sections) {
    $sections[] = new MyDocSection();
    
    return $sections; 
}

add_filter($page->getSectionsHook(), 'ghwp_add_doc_section');
// OR, using 'ghwp_filter_sections_' and the page's slug:
add_filter('ghwp_filter_sections_extras', 'ghwp_add_doc_section');

use Gebruederheitz\Wordpress\AdminPage\AbstractAdminPageSection;

class MyDocsSection extends AbstractAdminPageSection {
    public function getTitle() : string{
        return 'Documentation for my amazing feature';
    }
    
    protected function getDefaultPartial() : string{
        return __DIR__. '/../template-parts/meta/docs/feature.php';
    }
    /* Optional: Define an override path that can be used instead of your default */
    protected function getOverridePath() : string{
        return get_theme_file_path('template-parts/meta/overrides/feature.php');
    }
    
    /* Optional: Expose public methods for your template to use */
    public function getSomeData() {
        return [/* ... */];
    }
}

 # template-parts/meta/docs/feature.php
    [$docs, $section] = $args;

use Gebruederheitz\Wordpress\AdminPage\AdminPageSectionInterface
use Gebruederheitz\Wordpress\AdminPage\AbstractAdminPageSection;

class MySecondDocsSection extends AbstractAdminPageSection {
    /* ... */
    
    /**
     * @override
     */
    public function render(AdminPage $docs) 
    {
        get_template_part('template-parts/meta/docs/documentation', 'page', [$docs, $this]);
    }
}

/** Example of a section not extending the abstract base implementation */
class MyThirdDocsSection implements AdminPageSectionInterface {
    public function onPageSections(array $sections): array
    {
        $sections[] = $this;
        return $sections;
    } 
    
    public function getTitle(): string 
    {
        return 'My Third Docs Section is the best to date!';
    }
    
    public function render(DocumentationMenu $docs) 
    {
        get_template_part('template-parts/meta/docs/documentation', 'page', [$docs, $this]);
    }
    
}

# functions.php (or controller class)
use Gebruederheitz\Wordpress\AdminPage\Documentation\DocumentationMenu;

new DocumentationMenu();

new DocumentationMenu([$sectionOne, $sectionTwo]);

new \Gebruederheitz\Wordpress\Documentation\DocumentationMenu(null, 'Theme Docs!');

new DocumentationMenu(null, null, 'template-parts/special/docs.php');

use Gebruederheitz\Wordpress\AdminPage\Documentation\DocumentationMenu;
use Gebruederheitz\Wordpress\AdminPage\Documentation\Section\Shortcodes;
use Gebruederheitz\Wordpress\AdminPage\Documentation\Section\Icons;

new DocumentationMenu(
    'My Theme',
    [
        new Shortcodes(),
        new Icons(),
    ]   
);
// or
$docs = new DocumentationMenu();
$docs->addSection(new Shortcodes())->addSection(new Icons());
// or
$docs->addSections([new Shortcodes(), new Icons()]);
// or
add_filter($docs->getSectionsHook(), function(array $sections): array {
    $sections[] = new Shortcodes();
    
    return $sections;
});

use Gebruederheitz\Wordpress\AdminPage\Documentation\Attributes\DocumentationSection;

#[DocumentationSection(
    title: "My Feature",
    description: "<p>This is some <strong>content</strong> for my feature documentation.</p>"
)]
class MyDocumentedFeature {
    public function __construct() 
    {
        DocumentationSection::register($this);
        // or: DocumentationSection::register(self::class);
    }
}

// Using a regular AdminPage
\Gebruederheitz\Wordpress\AdminPage\AdminPage::factory('docs')
->processGenericSections();

// Using the DocumentationMenu constructor
new \Gebruederheitz\Wordpress\AdminPage\Documentation\DocumentationMenu(
    sections: [/* ... */],
    processGenericSections: true // <-- enable processing
)
// or using the method
$docs = new \Gebruederheitz\Wordpress\AdminPage\Documentation\DocumentationMenu(/* ... */);
$docs->processGenericSections();

use Gebruederheitz\Wordpress\AdminPage\Documentation\Attributes\DocumentationSection;
#[DocumentationSection(
    title: "My Markdown Feature",
    description: <<< 'EOL'
        ### Markdown is awesome
        
        This is some **Markdown** content for my feature documentation.
        
        - It supports lists
        - And other _cool_ stuff
        
        

use Gebruederheitz\Wordpress\AdminPage\Documentation\Attributes\ShortcodeDocumentation;

#[ShortcodeDocumentation(
    shortcode: "ghwp-my-shortcode",
    description: "Renders a thing.",
    parameters: [
        "id" => "The post ID you wish to display.",
    ],
    examples: [
        "[ghwp-my-shortcode id=123 /]"
    ]
)]
class MyShortcode {
    
    /* With a dynamic class instance... */
    public function __construct() 
    {
        ShortcodeDocumentation::register($this);
        // or: ShortcodeDocumentation::register(self::class);
        add_shortcode('ghwp-my-shortcode', [$this, 'renderShortcode'));
    }
    
    /* ...or with a static class / method */
    public static function init() 
    {
        ShortcodeDocumentation::register(self::class);
        add_shortcode('ghwp-my-shortcode', [self::class, 'renderShortcode']);
    }
}

MyShortcode::init();
/* or*/
new MyShortcode();

use Gebruederheitz\Wordpress\AdminPage\Documentation\Attributes\ShortcodeDocumentation;
use Gebruederheitz\Wordpress\AdminPage\Documentation\Section\Shortcodes;

/**
 * @ShortcodeDocumentation(
 *     shortcode="ghwp-my-shortcode",
 *     description="Renders a thing.",
 *     parameters={
 *       "id": "The post ID you wish to display."
 *     },
 *     examples={
 *       "[ghwp-my-shortcode id=123 /]"
 *     }
 *  )
 */
#[ShortcodeDocumentation(/* ... */)]
class MyShortcode {
    
    public function __construct() 
    {
        add_filter(
            Shortcodes::HOOK_SHORTCODE_DOCS,
            fn(array $docs) => [...$docs, self::class],
        );
        add_shortcode('ghwp-my-shortcode', [$this, 'renderShortcode'));
    }
}

 # template-parts/meta/docs/shortcodes.php
    [$docs, $section] = $args;

class MyShortcodes extends Shortcodes {
    // skip this if you want to keep the default partial and only
    // change the override location
    protected function getDefaultPartial(): string
    {
        return __DIR__ . '/../../templates/shortcodes.php';
    }

    protected function getOverridePath(): string
    {
        return 'template-parts/meta/docs/shortcodes.php';
    }
}

- use Gebruederheitz\Wordpress\AdminPage\Documentation\Annotations\ShortcodeDocumentation;
+ use Gebruederheitz\Wordpress\AdminPage\Documentation\Attributes\ShortcodeDocumentation;
- use Gebruederheitz\Wordpress\AdminPage\Documentation\Traits\withShortcodeDocumentation;

- /**
-  * @ShortcodeDocumentation(
-  *   shortcode="ghwp-my-shortcode", 
-  *   description="Renders a thing.",
-  *   parameters={
-  *       "id": "The post ID you wish to display."
-  *   },
-  *   examples={
-  *     "[ghwp-my-shortcode id=123 /]"
-  *   }
-  * )
-  */
+ #[ShortcodeDocumentation(
+   shortcode: "ghwp-my-shortcode",
+   description: "Renders a thing.",
+   parameters: [
+       "id" => "The post ID you wish to display."
+   ],
+   examples: [
+       "[ghwp-my-shortcode id=123 /]"
+   ]
+ )]
+
class MyShortcode {
-    use withShortcodeDocumentation;
    
    public function __construct() 
    {
-        $this->addDocumentation();
+        ShortcodeDocumentation::register($this);
        add_shortcode('ghwp-my-shortcode', [$this, 'renderShortcode'));
    }

use Gebruederheitz\Wordpress\AdminPage\Documentation\Attributes\ShortcodeDocumentation;
- use Gebruederheitz\Wordpress\AdminPage\Documentation\Traits\withShortcodeDocumentation;
+ use Gebruederheitz\Wordpress\AdminPage\Documentation\Traits\WithShortcodeDocumentation;

#[ShortcodeDocumentation(
  shortcode: "ghwp-my-shortcode",
  description: "Renders a thing.",
  parameters: [
      "id" => "The post ID you wish to display."
  ],
  examples: [
      "[ghwp-my-shortcode id=123 /]"
  ]
)]
class MyShortcode {
-    use withShortcodeDocumentation;
+    use WithShortcodeDocumentation;
    
    public function __construct() 
    {
        $this->addDocumentation();
        add_shortcode('ghwp-my-shortcode', [$this, 'renderShortcode'));
    }

    EOL,
    markdown: true
)]
class MyDocumentedFeature {
    public function __construct() 
    {
        DocumentationSection::register($this);
    }
}