Merge pull request #1337 from 10up/docs/1336

Replace hookdoc with WP Hooks Documentor

Author: dkotter

.eslintignore

@@ -4,6 +4,7 @@ dist/*
 docs-built/*
 vendor/*
 gulp-tasks/*
+wp-hooks-docs/*
 tests/cypress/reports/*
 tests/cypress/videos/*
 tests/cypress/screenshots/*

.github/hookdoc-tmpl/layout.tmpl

@@ -1,4 +1,4 @@
-name: Build Hook Docs
+name: Build Developer Docs
 
 on:
  push:
@@ -11,13 +11,18 @@ jobs:
     steps:
     - 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: Use desired version of NodeJS
       uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
       with:
-          node-version-file: '.nvmrc'
+          node-version: 20
 
     - name: Check versions
-      run: npm -v; node -v
+      run: npm -v; node -v; php -v
 
     - name: npm install, and build docs
       run: |
@@ -31,4 +36,4 @@ jobs:
       uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: './docs-built'
+        publish_dir: './docs-built/build'

.github/hookdoc-tmpl/static/styles-10up.css

@@ -17,3 +17,5 @@ tests/cypress/reports
 tests/cypress/downloads
 
 distributor.zip
+/wp-hooks-docs/docs/hooks
+/wp-hooks-docs/docs/01.get-started/05.CHANGELOG.md

.github/workflows/build-docs.yml

@@ -167,9 +167,39 @@ By default, drafts are the preferred status and can't be changed at the source s
 
 Oftentimes the communication Distributor attempts to make across sites using the REST API will be flagged by various security plugins and surreptitiously blocked.  If you run into an issue like this, please reach out to the support for your security plugin and ask about getting Distributor unblocked ([here is an example for doing so with Wordfence](https://wordpress.org/support/topic/distributor-plugin-being-blocked/)).
 
+## Building and Running Documentation Site
+
+The Distributor documentation site is built using [WP Hooks Documentor](https://github.com/10up/wp-hooks-documentor). Follow these steps to build and run the documentation site locally:
+
+### 1. Build Documentation
+Node.js >= 20.0 and PHP >= 8.3 will be needed in your development environment.
+
+```bash
+# Install dependencies and build the plugin
+npm i && npm run build:docs
+```
+
+This will:
+- Install all required dependencies
+- Process all hook documentation from the codebase
+- Generate the documentation site in the `./docs-built` directory
+
+### 2. Run Documentation Site Locally
+
+```bash
+# Navigate to docs-built directory and start the server
+cd ./docs-built && npm run serve
+```
+
+The documentation site will be available at [http://localhost:3000](http://localhost:3000).
+
+### 3. Deployment
+
+The documentation site will automatically deploy to GitHub Pages when changes are merged into the `trunk` branch. You can view the live documentation at [https://10up.github.io/distributor/](https://10up.github.io/distributor/).
+
 ## Developers
 
-See [Distributor Developer Documentation](https://10up.github.io/distributor/#developers).
+See [Distributor Developer Documentation](https://10up.github.io/distributor/get-started/developers).
 
 ## Frequently Asked Questions
 

.gitignore

@@ -50,11 +50,10 @@ function enabled() {
 	 * to. These posts will be distributed as published posts, not drafts.
 	 *
 	 * @since 2.2.0
-	 * @hook dt_auto_distribution_enabled
 	 *
-	 * @param {bool} $enabled Whether the auto-distribution feature is enabled. Default false.
+	 * @param bool $enabled Whether the auto-distribution feature is enabled. Default false.
 	 *
-	 * @return {bool} Whether the auto-distribution feature is enabled.
+	 * @return bool Whether the auto-distribution feature is enabled.
 	 */
 	return apply_filters( 'dt_auto_distribution_enabled', false );
 }
@@ -77,12 +76,11 @@ function default_post_status( $post ) {
 	 * Filter the default status for auto-distributed posts.
 	 *
 	 * @since 2.2.0
-	 * @hook dt_auto_distribution_default_status
 	 *
-	 * @param {string}  $status Default status for auto-distributed posts. Default 'publish'.
-	 * @param {WP_Post} $post   Post object for the post being pushed.
+	 * @param string  $status Default status for auto-distributed posts. Default 'publish'.
+	 * @param WP_Post $post   Post object for the post being pushed.
 	 *
-	 * @return {string} Default status for auto-distributed posts.
+	 * @return string Default status for auto-distributed posts.
 	 */
 	return apply_filters( 'dt_auto_distribution_default_status', 'publish', $post );
 }
@@ -111,15 +109,14 @@ function auto_distribute_post( $post, $user_id, $connection_type, $connection_id
 	 * Filter to determine if a post should be auto-distributed.
 	 *
 	 * @since 2.2.0
-	 * @hook dt_auto_distribute_post
 	 *
-	 * @param {bool}    $should_distribute Whether the post should be auto-distributed.
-	 * @param {WP_Post} $post              WP_Post object for the post being pushed.
-	 * @param {int}     $user_id           User ID of the user pushing the post.
-	 * @param {string}  $connection_type   Type of connection ('external' or 'internal').
-	 * @param {int}     $connection_id     Connection ID.
+	 * @param bool    $should_distribute Whether the post should be auto-distributed.
+	 * @param WP_Post $post              WP_Post object for the post being pushed.
+	 * @param int     $user_id           User ID of the user pushing the post.
+	 * @param string  $connection_type   Type of connection ('external' or 'internal').
+	 * @param int     $connection_id     Connection ID.
 	 *
-	 * @return {bool} Whether the post should be auto-distributed.
+	 * @return bool Whether the post should be auto-distributed.
 	 */
 	return apply_filters( 'dt_auto_distribute_post', true, $post, $user_id, $connection_type, $connection_id );
 }
@@ -140,11 +137,10 @@ function auto_distribute_supported_post_types() {
 	 * Filter the post types that are auto-distributable.
 	 *
 	 * @since 2.2.0
-	 * @hook auto_distribute_supported_post_types
 	 *
-	 * @param {string[]} $post_types Array of post types that can be auto-distributed.
+	 * @param string[] $post_types Array of post types that can be auto-distributed.
 	 *                               Default is array( 'post', 'page' ).
-	 * @return {string[]} Array of post types that can be auto-distributed.
+	 * @return string[] Array of post types that can be auto-distributed.
 	 */
 	return apply_filters( 'auto_distribute_supported_post_types', $post_types );
 }
@@ -318,12 +314,10 @@ function get_external_connections( $post_id = 0, $user_id = 0 ) {
 			 * Modify the maximum number of external connection post types are
 			 * queried with requesting the post type.
 			 *
-			 * @hook dt_external_connections_per_page
-			 *
 			 * @since 2.2.0
 			 *
-			 * @param {int} $max_connections The maximum number of external connections to load.
-			 * @return {int} The maximum number of external connections to load.
+			 * @param int $max_connections The maximum number of external connections to load.
+			 * @return int The maximum number of external connections to load.
 			 */
 			'posts_per_page' => apply_filters( 'dt_external_connections_per_page', 200 ), // @codingStandardsIgnoreLine This high pagination limit is purposeful
 		]

README.md

@@ -209,11 +209,10 @@ function() {
 			 * Filter whether the network connection type is enabled. Enabled by default, return false to disable.
 			 *
 			 * @since 1.0.0
-			 * @hook dt_network_site_connection_enabled
 			 *
-			 * @param {bool} true Whether the network connection should be enabled.
+			 * @param bool true Whether the network connection should be enabled.
 			 *
-			 * @return {bool} Whether the network connection should be enabled.
+			 * @return bool Whether the network connection should be enabled.
 			 */
 			apply_filters( 'dt_network_site_connection_enabled', true )
 		) {