10up Actions for WordPress

WP Hooks Documentor relies on standard WordPress PHPDoc comments to extract hook information. It detects apply_filters() for filters and do_action() for actions.

To ensure hooks are correctly documented, include:

• A description of the hook.
• @since version tag.
• @param tags with types and descriptions for all arguments.
• @return tag for filter hooks.

Filter Example

/**
 * Filters the taxonomies that should be synced.
 *
 * @since 1.0.0
 *
 * @param array   $taxonomies Associative array list of taxonomies supported by current post in the format of `$taxonomy => $terms`.
 * @param WP_Post $post       The post object.
 * 
 * @return array Associative array list of taxonomies supported by current post in the format of `$taxonomy => $terms`.
 */
$taxonomies = apply_filters( 'dt_syncable_taxonomies', $taxonomies, $post );

Action Example

/**
 * Fires the action after a post is pushed via Distributor before remote request validation.
 *
 * @since 2.0.0
 *
 * @param array|WP_Error              $response    The response from the remote request.
 * @param array                       $post_body   The Post data formatted for the REST API endpoint.
 * @param string                      $type_url    The Post type api endpoint.
 * @param int                         $post_id     The Post id.
 * @param array                       $args        The arguments passed into wp_insert_post.
 * @param WordPressExternalConnection $this        The Distributor connection being pushed to.
 */
do_action( 'dt_push_external_post', $response, $post_body, $type_url, $post_id, $args, $this );

You can automate the generation and deployment of your hook documentation using a GitHub Actions workflow.

Workflow Requirements

• A workflow file in .github/workflows/.
• The workflow must install dependencies, run the documentation generation command, and use an action like peaceiris/actions-gh-pages to deploy the publish_dir to the gh-pages branch.

Example Workflow (.github/workflows/build-docs.yml)

name: Build Hook Documentation

on: push:
  branches:
    - trunk

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Setup proper PHP version
        uses: shivammathur/setup-php@9e72090525849c5e82e596468b86eb55e9cc5401 # v2.32.0
        with:
          php-version: 8.3

      - name: Setup node
        uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
        with:
          node-version: 20

      - name: npm install, and build docs
        run: |
          npm install
          npm run build:docs
         
      - name: Deploy to GH Pages
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: './docs/build'

You can convert PHP CodeSniffer (PHPCS) JSON reports into Markdown summaries for the GitHub Actions job summary. This uses the phpcs-json-to-md tool.

Steps to implement:

1. Configure your PHPCS check (e.g., using 10up/wpcs-action) to output a JSON report using the --report-json argument.
2. Use npx github:10up/phpcs-json-to-md to convert the JSON report to a Markdown file.
3. Append the Markdown file to $GITHUB_STEP_SUMMARY.
4. Use the conditional if: ${{ failure() }} to ensure the summary is only updated when the PHPCS check fails.

jobs:
  phpcs:
    name: WPCS
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: WPCS check
        uses: 10up/wpcs-action@stable
        with:
          use_local_config: true
          extra_args: '--report-json=./phpcs-report.json'
      - name: Update summary
        run: |
          npx github:10up/phpcs-json-to-md --path ./phpcs-report.json --output ./phpcs-report.md
          cat phpcs-report.md >> $GITHUB_STEP_SUMMARY
        if: ${{ failure() }}

To improve developer experience, you can convert ESLint JSON reports into readable Markdown summaries in the GitHub Actions job summary. This is achieved by using the eslint-json-to-md tool to convert the JSON report to Markdown, and then appending that Markdown content to the $GITHUB_STEP_SUMMARY environment variable.

Key implementation details:

• Use the --output-file flag with your linting command to generate a JSON report.
• Use npx github:10up/eslint-json-to-md to perform the conversion.
• Append the resulting file to $GITHUB_STEP_SUMMARY using cat.
• It is recommended to run the summary update step only if: ${{ failure() }} so that reports are only generated when linting issues are actually found.

jobs:
  eslint:
    name: eslint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: npm install
        run: npm install
      - name: Generate linting report
        run: npm run lint:js -- --output-file eslint-report.json --format json
        continue-on-error: true
      - name: Annotate code linting results
        uses: ataylorme/eslint-annotate-action@1.2.0
        with:
          repo-token: '${{ secrets.GITHUB_TOKEN }}'
          report-json: 'eslint-report.json'
      - name: Update summary
        run: |
          npm_config_yes=true npx github:10up/eslint-json-to-md --path ./eslint-report.json --output ./eslint-report.md
          cat eslint-report.md >> $GITHUB_STEP_SUMMARY
        if: ${{ failure() }}