Documentation Generator for WordPress.

Overview

Pronamic WordPress Documentor

Pronamic WordPress Documentor

Pronamic WordPress Documentor is a tool to automatically extract data about the actions and filters of your WordPress theme or plugin.

Latest Stable Version Total Downloads Latest Unstable Version License

Table of contents

Getting Started

Installation

To start documenting your WordPress filters and actions, require Pronamic WordPress Documentor in Composer:

composer require pronamic/wp-documentor --dev

First Run

To let Pronamic WordPress Documentor analyse your codebase, you have to use the parse command and point it to the right directory:

vendor/bin/wp-documentor parse src

Command Line Usage

--format=FORMAT

The format in which you want to export the hooks.

Format Description
default Symfony console table.
hookster Hookster JSON.
markdown Markdown.
phpdocumentor-rst RestructuredText for phpDocumentor.

Example: --format=markdown

--template=FILE

Custom PHP template, see for examples the templates folder.

Example: --template=templates/markdown.php

--type=TYPE

Specify whether you want to export actions or filters.

Example: --type=actions or --type=filters

--output=FILE

Write output to file.

Example: --output=docs/hooks.md

--memory-limit=VALUE

Specifies the memory limit in the same format php.ini accepts.

Example: --memory-limit=-1

--exclude=GLOB

Exclude the specified folders/files.

Example: --exclude=vendor --exclude=wordpress

--ignore-vcs-ignored

If the search directory contains a .gitignore file, you can reuse those rules to exclude files and directories from the results with this option.

Example: --ignore-vcs-ignored

Examples

vendor/bin/wp-documentor parse ./tests/source
vendor/bin/wp-documentor parse ./tests/source --format=hookster --type=actions --output=tests/docs/hookster-actions.json
vendor/bin/wp-documentor parse ./tests/source --format=hookster --type=filters --output=tests/docs/hookster-filters.json
vendor/bin/wp-documentor parse ./tests/source --format=markdown --output=tests/docs/hooks.md
vendor/bin/wp-documentor parse ./tests/source --format=phpdocumentor-rst --type=actions --output=tests/docs/phpdocumentor-actions.rst
vendor/bin/wp-documentor parse ./tests/source --format=phpdocumentor-rst --type=filters --output=tests/docs/phpdocumentor-filters.rst

Ouput Examples

Alternatives

Here is a list of alternatives that we found. However, none of these satisfied our requirements.

If you know other similar projects, feel free to edit this section!

Inspiration from https://github.com/TypistTech/imposter-plugin#alternatives

Links

Comments
  • Cannot exclude single file

    Cannot exclude single file

    I have an issue trying to exclude single files, using the --exclude argument

    It works fine when I exclude a whole folder, yet I just want to exclude one file. It seems to ignore the --exclude statement, if I pass a valid filename, but it works when I pass a valid folder name.

    Example: --exclude=foldername => works (excludes whole foldername folder) --exclude=filename.php => fails (does not exclude that file)

    I have also tried with foldername/filename and different other syntax, inclusive brackets, and it just seems to ignore it when the name passed is not a folder.

    According the description however it seems it should be possible to exclude single files? Even better would be to exclude occurrences it cannot parse and just skip. I have a peculiar plugin that does something like this: do_action( $atts['hook_name'] );

    Of course, that hook fails in the parser with these errors:

    Not supported hook tag expression `PhpParser\Node\Expr\ArrayDimFetch`: $att  
      s['hook_name'].   
    Could not convert tag argument value to a name in path/to/file/filename.php#N. 
    

    This is why I want to exclude that file, but of course if there's an easy way to just skip when failing, instead of halting, that would be the best!

    opened by smileBeda 3
  • Ensure to not print the same hook too often

    Ensure to not print the same hook too often

    Happens that sometimes a codebase does apply_filters or do_action the same hook more than once. With the current template, you then get a DOC with each instance of that apply_filters or do_action repeated as many times as the codebase uses it.

    For example, if you use a apply_filters( 'list_cats', $r['show_option_all'], null ) more than once (WP does that), your doc would result in a list of several list_cats, instead of just one, but you'd not want that.

    With the proposed change, the filter or action, if already printed, will be skipped. It might not be the best solution but avoids n-plicated occurrences of the same filter/action

    NOTE The template as such for me was not functional, I had to make changes to get it working, but those changes I will provide in another PR (if that's OK)

    opened by smileBeda 3
  • Add support for `@ignore` tag

    Add support for `@ignore` tag

    Add support for the @ignore tag:

    • https://github.com/pronamic/wp-documentor/issues/13

    Also see:

    • https://docs.phpdoc.org/guide/references/phpdoc/tags/ignore.html
    • https://pear.php.net/package/PhpDocumentor/docs/latest/phpDocumentor/tutorial_tags.ignore.pkg.html

    @ignore

    The @ignore tag is used to tell phpDocumentor that Structural Elements are not to be processed by phpDocumentor.

    Syntax

    @ignore [<description>]
    
    opened by remcotolsma 2
  • Add support for `prefix` option

    Add support for `prefix` option

    A new --prefix option will allow limiting the output to hooks matching the prefixes passed as a comma-separated list. For example, --prefix=my_theme,my_plugin would include my_theme_some_hook and my_plugin_some_other_hook but exclude not_my_hook from the output.

    This can be useful when developers need to document the proprietary action and filter hooks introduced by their theme or plugin.

    enhancement 
    opened by LuigiPulcini 2
  • List of arguments is empty when `apply_filters` is returned instead of assigned to variable

    List of arguments is empty when `apply_filters` is returned instead of assigned to variable

    There seems to be a difference in the output between the two following occurrences:

    <?php
    /**
     * My plugin filter assigned to a variable
     *
     * @param string $first_param This is the first argument
     * @param string $second_param This is the second argument
     */
    $some_variable = apply_filters( 'my_plugin_filter', $first_param, $second_param );
    
    return $some_variable;
    
    <?php
    /**
     * My plugin filter directly returned
     *
     * @param string $first_param This is the first argument
     * @param string $second_param This is the second argument
     */
    return apply_filters( 'my_plugin_filter', $first_param, $second_param );
    

    In the first case, the full list of arguments is correctly parsed. In the second case, the list of arguments is empty.

    opened by LuigiPulcini 1
  • Add ability to ignore a specific hook

    Add ability to ignore a specific hook

    I think we as developers should be able to add something to the phpdoc of a hook to let wp-documentor know that it should NOT be documented. This is because some applications enqueue hooks so dynamic that it has no value.

    Maybe something like this?

    /**
     * @ignore
     */
    $result = apply_filters($hook, $queue, $parameter);
    

    edit: this could also be handy when using the result of native WP hooks in your project, such as https://developer.wordpress.org/reference/hooks/the_content/

    opened by niels-bosman 0
  • Render @link tags in markdown template

    Render @link tags in markdown template

    Currently the @link tags are not rendered in the markdown template.

    /**
     * Prints scripts or data in the head tag on the Adyen checkout page.
     * 
     * This action can be used, for example, to register and print a custom style.
     *
     * See the following link for an example:
     * https://github.com/wp-pay-gateways/adyen#pronamic_pay_adyen_checkout_head
     *
     * @link https://github.com/WordPress/WordPress/blob/5.7/wp-includes/general-template.php#L3004-L3009
     *
     * @since 1.1
     */
    do_action( 'pronamic_pay_adyen_checkout_head' );
    

    https://github.com/wp-pay-gateways/adyen/blob/62425e3706d32c63697cd31dbd57ba0894a60118/views/head.php#L8-L19

    https://github.com/wp-pay-gateways/adyen/blob/develop/docs/hooks.md#pronamic_pay_adyen_checkout_head

    enhancement 
    opened by remcotolsma 0
  • Add a way to separate actions and filters in different (markdown) files

    Add a way to separate actions and filters in different (markdown) files

    bin/wp-documentor parse wordpress --format=markdown --type=actions --relative=tests/docs --memory-limit=-1 --output=tests/docs/wordpress-actions.md
    
    bin/wp-documentor parse wordpress --format=markdown --type=filters --relative=tests/docs --memory-limit=-1 --output=tests/docs/wordpress-filters.md
    
    opened by remcotolsma 0
Releases(1.3.0)
Owner
Pronamic
We are a Frisian WordPress Development Agency from the Netherlands.
Pronamic
Documentation Generator for WordPress.

Pronamic WordPress Documentor is a tool to automatically extract data about the actions and filters of your WordPress theme or plugin.

Pronamic 35 Nov 11, 2022
Documentation Generator for PHP

phpDocumentor What is phpDocumentor? phpDocumentor is an application that is capable of analyzing your PHP source code and DocBlock comments to genera

phpDocumentor 3.7k Nov 29, 2022
An API documentation generator

Sami: an API documentation generator WARNING: Sami is not supported nor maintained anymore. Feel free to fork. Curious about what Sami generates? Have

null 2k Nov 3, 2022
Documentation generator for PHP Code using standard technology (SRC, DOCBLOCK, XML and XSLT)

phpDox phpDox is a documentation generator for PHP projects. This includes, but is not limited to, API documentation. The main focus is on enriching t

Arne Blankerts 589 Nov 11, 2022
A php API documentation generator, fork of Sami

Doctum, a PHP API documentation generator. Fork of Sami Curious about what Doctum generates? Have a look at the MariaDB MySQL Kbs or Laravel documenta

Code LTS 195 Nov 20, 2022
Sami: an API documentation generator

Sami: an API documentation generator WARNING: Sami is not supported nor maintained anymore. Feel free to fork. Curious about what Sami generates? Have

null 2k Nov 3, 2022
PHP 7.1 ready Smart and Simple Documentation for your PHP project

Smart and Readable Documentation for your PHP project ApiGen is the simplest, the easiest to use and the most modern api doc generator. It is all PHP

ApiGen 2.1k Nov 27, 2022
PHP 7.1 ready Smart and Simple Documentation for your PHP project

Smart and Readable Documentation for your PHP project ApiGen is the simplest, the easiest to use and the most modern api doc generator. It is all PHP

ApiGen 2.1k Apr 20, 2021
Generates documentation for your REST API from annotations

NelmioApiDocBundle The NelmioApiDocBundle bundle allows you to generate a decent documentation for your APIs. Migrate from 3.x to 4.0 To migrate from

Nelmio 2.1k Nov 25, 2022
phpDocumentor is an application that is capable of analyzing your PHP source code and DocBlock comments to generate a complete set of API Documentation

phpDocumentor What is phpDocumentor? phpDocumentor is an application that is capable of analyzing your PHP source code and DocBlock comments to genera

phpDocumentor 3.7k Dec 1, 2022
Generate interactive OpenAPI documentation for your RESTful API using doctrine annotations

Generate interactive OpenAPI documentation for your RESTful API using doctrine annotations

Robert Allen 4.6k Nov 24, 2022
Generate Sphinx/ReStructured documentation from PHPDoc

PHP-phpdoc-to-rst Forked from Francesco "Abbadon1334" Danti by AeonDigital. In this fork the changes has only visual and superficial effects [ just be

Rianna Cantarelli 0 Nov 16, 2021
WordPress Tiny Snippets

WordPress Tiny Snippets [+] :: Info/Инфо: [ ???? ] Collection of tiny snippets for WordPress CMS.

m0ze 2 Dec 19, 2021
Daux.io is an documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you create great looking documentation in a developer friendly way.

Daux.io Daux.io is a documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It help

Daux.io 719 Nov 29, 2022
Documentation Generator for WordPress.

Pronamic WordPress Documentor is a tool to automatically extract data about the actions and filters of your WordPress theme or plugin.

Pronamic 35 Nov 11, 2022
Documentation Generator for PHP

phpDocumentor What is phpDocumentor? phpDocumentor is an application that is capable of analyzing your PHP source code and DocBlock comments to genera

phpDocumentor 3.7k Nov 29, 2022
An API documentation generator

Sami: an API documentation generator WARNING: Sami is not supported nor maintained anymore. Feel free to fork. Curious about what Sami generates? Have

null 2k Nov 3, 2022
Documentation generator for PHP Code using standard technology (SRC, DOCBLOCK, XML and XSLT)

phpDox phpDox is a documentation generator for PHP projects. This includes, but is not limited to, API documentation. The main focus is on enriching t

Arne Blankerts 589 Nov 11, 2022
A php API documentation generator, fork of Sami

Doctum, a PHP API documentation generator. Fork of Sami Curious about what Doctum generates? Have a look at the MariaDB MySQL Kbs or Laravel documenta

Code LTS 195 Nov 20, 2022
Laravel API Documentation Generator

Laravel API Documentation Generator Automatically generate your API documentation from your existing Laravel/Lumen/Dingo routes. php artisan apidoc:ge

Marcel Pociot 3.3k Nov 26, 2022