pentatonicfunk / wp-phpdoc-markdown Goto Github PK

0.0 2.0 0.0 27 KB

Wordpress PHPDoc to Markdown

License: GNU General Public License v2.0

PHP 100.00%

wp-phpdoc-markdown's Introduction

WP phpDoc Markdown

Create Markdown documentations for WordPress Code. Currently its only creating docs for hooks. Functions and Classes not included yet.

History and Credits

This project is based on WordPress/phpdoc-parser.

Inline documentation should follow WordPress Best Practices

Sample Output : example.md

Requirements

PHP 5.4+
Composer
WP CLI

Clone the repository into your WordPress plugins directory:

git clone [email protected]:pentatonicfunk/wp-phpdoc-markdown.git

After that install the dependencies using composer in the parser directory:

composer install

Running

Activate the plugin first:

wp plugin activate wp-phpdoc-markdown

In your site's directory / wp-phpdoc-markdown directory:

wp wparser mdhooks <src_dir> <output_dir> [--json_doc=<json_doc>]
wp wparser mdhooks ../forminator/ ./../forminator/docs

Customization

All default used templates are placed in templates

To Customize it define this constant in your wp-config.php

define( 'WP_PHPDOC_MARKDOWN_TEMPLATE_TOC', '/path/to/toc.md' );
define( 'WP_PHPDOC_MARKDOWN_TEMPLATE_HOOK', __DIR__ . '/path/to/hook.md' );
define( 'WP_PHPDOC_MARKDOWN_TEMPLATE_HOOK_PARAMETERS', '/path/to/hook.parameters.md' );
define( 'WP_PHPDOC_MARKDOWN_TEMPLATE_HOOK_PARAMETER', '/path/to/hook.parameter.md' );
define( 'WP_PHPDOC_MARKDOWN_TEMPLATE_HOOK_CHANGELOGS', '/path/to/hook.changelogs.md' );
define( 'WP_PHPDOC_MARKDOWN_TEMPLATE_HOOK_CHANGELOG', '/path/to/hook.changelog.md' );

Usage Help

NAME

wp wparser mdhooks

DESCRIPTION

Generate a JSON file containing the PHPDoc markup, and create markdown docs of hooks on <output_dir>.

SYNOPSIS

wp wparser mdhooks <src_dir> <output_dir> [--json_doc=<json_doc>]

OPTIONS

<src_dir>
    Source code directory

<output_dir>
    Desired Output directory of markdown documents

[--json_doc=<json_doc>]
    Where temporary generated json phpdoc will be created, default is /tmp/phpdoc.json

EXAMPLES

wp wparser mdhooks <src_dir> <output_dir> [--json_doc=<json_doc>]
wp wparser mdhooks ../forminator/ ./../forminator/docs --json_doc=/tmp/phpdoc.json

wp-phpdoc-markdown's People

Contributors

Watchers

wp-phpdoc-markdown's Issues

Docs Versioning

Add Docs versioning on generated Markdown

Proposed Solution:

Generate markdown in temporary directory which can be configured on wp cli
Comparing the contents of generated docs with currently available docs using hash
If nothing change, inform it on cli output, do not replace available docs
If changes inform which hooks is deleted or added on cli output, replace available docs
Update generated timestamp on README.md

Duplicate hooks detection

Currently, wp-phpdoc-markdown is not detecting any duplicate hooks, and process it as different hooks, even these hooks have same tag.

Proposed Solution :

Collect duplicate hooks and process it as same hook.
For generated markdown on README.md, list it as one
For generated markdown on the hooks detail section Source make it as a list and list all files that include this hooks.

Possible Problem :

Same hook tag used but, different arg(s) used.
Possible solutions for this are: stop current process and inform user about it because its high likely developer mistakes. Or add a options to allow different arg(s) which will be then will mark these duplicated hook(s) as different hooks. Or add a confirmation message each time different arg(s)
detected.

Unit Test

No unit test ? you suck!

Show type (hinting) for arguments on Example Usage in generated markdown

Current

<?php
function add_filter_forminator_addon_mailchimp_metadata( $addon_meta_data, $form_id, $form_settings_instance ){
    // do some filters.

    return $addon_meta_data;
}
add_filter( "forminator_addon_mailchimp_metadata", "add_filter_forminator_addon_mailchimp_metadata" );

Improvement:

<?php
function add_filter_forminator_addon_mailchimp_metadata( array $addon_meta_data, int $form_id, \Forminator_Addon_Mailchimp_Form_Settings $form_settings_instance ){
    // do some filters.

    return $addon_meta_data;
}
add_filter( "forminator_addon_mailchimp_metadata", "add_filter_forminator_addon_mailchimp_metadata" );

$accepted_args not included in Example

Describe the bug
$accepted_args not included in Example which is important, because by default its only 1

To Reproduce
Steps to reproduce the behavior:

Run wp wparser mdhooks
Go to output
See its not generated

Expected behavior
$accepted_args added

Additional context
Since if we specify $accepted_args we need specify $priority, i guess make sense to use 10 and probably add option for that