From deabdd84db06de47a2d4a96ea87f01cb933e56ce Mon Sep 17 00:00:00 2001 From: piinthecloud Date: Wed, 23 Jul 2025 13:39:08 +0200 Subject: [PATCH 1/5] add logic to ensure that the hooks inside of the woocommerce/src/ are being parsed and add some steps to run this site locally --- .gitignore | 2 +- README.md | 17 ++++++++ generate-hook-docs.php | 17 ++------ run-local.sh | 88 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 110 insertions(+), 14 deletions(-) create mode 100755 run-local.sh diff --git a/.gitignore b/.gitignore index cfd4ba8f3a..166d7ded9f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ *.zip build/ -woocommerce/ +woocommerce vendor/ !data/templates/woocommerce/ diff --git a/README.md b/README.md index 15c505cc08..d748b5f8f8 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,28 @@ git clone https://github.com/woocommerce/code-reference.git ## Usage +### Production Deployment + ```bash cd code-reference ./deploy.sh -s ``` +### Local Development + +For local development and testing with your own WooCommerce installation: + +```bash +cd code-reference +./run-local.sh +``` + +The script will prompt you for the path to your WooCommerce plugin directory. This should be the directory containing the main WooCommerce plugin files (e.g., `Users/YourUserName/woocommerce/plugins/woocommerce`). + +After generation, the Documenation will be served from the `build/api` folder. + +A local web server will start at `http://localhost:8000`. + ### Options | Options | Description | diff --git a/generate-hook-docs.php b/generate-hook-docs.php index ceccc068ef..c3365ffc57 100644 --- a/generate-hook-docs.php +++ b/generate-hook-docs.php @@ -54,9 +54,9 @@ protected static function getFilesToScan(): array self::getFiles('*.php', GLOB_MARK, self::SOURCE_PATH . 'includes/export/'), self::getFiles('*.php', GLOB_MARK, self::SOURCE_PATH . 'includes/gateways/'), self::getFiles('*.php', GLOB_MARK, self::SOURCE_PATH . 'includes/import/'), - self::getFiles('*.php', GLOB_MARK, self::SOURCE_PATH . 'includes/shipping/') + self::getFiles('*.php', GLOB_MARK, self::SOURCE_PATH . 'includes/shipping/'), + self::getFiles('*.php', GLOB_MARK, self::SOURCE_PATH . 'src/') ); - return array_filter($files); } @@ -108,18 +108,9 @@ protected static function getFiles($pattern, $flags = 0, $path = '') if (is_array($paths)) { foreach ($paths as $p) { - $found_files = []; $retrieved_files = (array) self::getFiles($pattern, $flags, $p . '/'); - foreach ($retrieved_files as $file) { - if (! in_array($file, self::$found_files)) { - $found_files[] = $file; - } - } - - self::$found_files = array_merge(self::$found_files, $found_files); - - if (is_array($files) && is_array($found_files)) { - $files = array_merge($files, $found_files); + if (is_array($files) && is_array($retrieved_files)) { + $files = array_merge($files, $retrieved_files); } } } diff --git a/run-local.sh b/run-local.sh new file mode 100755 index 0000000000..2b17d07b43 --- /dev/null +++ b/run-local.sh @@ -0,0 +1,88 @@ +#!/usr/bin/env bash +set -o errexit # Abort if any command fails + +echo "๐Ÿš€ WooCommerce Code Reference Generator - Local Development" +echo "==========================================================" + +# Check if PHP is available +if ! command -v php &> /dev/null; then + echo "โŒ PHP is not installed or not in PATH" + exit 1 +fi + +# Check if Composer is available +if ! command -v composer &> /dev/null; then + echo "โŒ Composer is not installed or not in PATH" + exit 1 +fi + +# Install dependencies if vendor directory doesn't exist +if [ ! -d "vendor" ]; then + echo "๐Ÿ“ฆ Installing dependencies..." + composer install +fi + +# Prompt user for WooCommerce directory +echo "๐Ÿ“ Please provide the path to your WooCommerce directory." +echo "Example: /Users/YourUserName/woocommerce/plugins/woocommerce" +echo "" + +# Read user input with a default suggestion +read -p "Enter WooCommerce directory path: " WOOCOMMERCE_DIR + + +# Check if directory exists +if [ ! -d "$WOOCOMMERCE_DIR" ]; then + echo "โŒ WooCommerce plugin directory not found at: $WOOCOMMERCE_DIR" + echo " Please check the path and try again." + exit 1 +fi + +echo "๐Ÿ“ Using WooCommerce plugin directory: $WOOCOMMERCE_DIR" + +# Create symbolic link to the WooCommerce directory +if [ -L "woocommerce" ]; then + echo "๐Ÿ”— Removing existing symbolic link..." + rm woocommerce +elif [ -d "woocommerce" ]; then + echo "๐Ÿ—‘๏ธ Removing existing woocommerce directory..." + rm -rf woocommerce +fi + +echo "๐Ÿ”— Creating symbolic link to local WooCommerce plugin directory..." +ln -s "$WOOCOMMERCE_DIR" woocommerce + +# Clean up any existing build +if [ -d "build" ]; then + echo "๐Ÿงน Cleaning up existing build..." + rm -rf build +fi + +echo "๐Ÿ”ง Generating documentation from local WooCommerce source..." +echo "" + +# Run PHPDocumentor directly with the local source +./vendor/bin/phpdoc run \ + --template="data/templates/woocommerce" \ + --sourcecode \ + --defaultpackagename="WooCommerce" + +# Generate hook documentation AFTER PHPDocumentor completes +echo "๐Ÿ”ง Generating hook documentation..." +php generate-hook-docs.php + +echo "" +echo "โœ… Documentation generated successfully!" +echo "๐Ÿ“ Output location: ./build/api/" +echo "๐Ÿ”— The symbolic link to your WooCommerce directory will remain for future builds." +echo " To remove it: rm woocommerce" +echo "" +echo "๐ŸŒ Starting local web server for WooCommerce Code Reference..." +echo "๐Ÿ“ Serving from: ./build/api" +echo "๐ŸŒ URL: http://localhost:8000" +echo "" +echo "Press Ctrl+C to stop the server" +echo "" + +# Start PHP development server +php -S localhost:8000 -t build/api \ No newline at end of file From 026b97bb4d7798562c8b6d5487c0c0fc4b71285a Mon Sep 17 00:00:00 2001 From: piinthecloud Date: Wed, 23 Jul 2025 14:34:07 +0200 Subject: [PATCH 2/5] remove unused reference --- generate-hook-docs.php | 7 ------- 1 file changed, 7 deletions(-) diff --git a/generate-hook-docs.php b/generate-hook-docs.php index c3365ffc57..20f7c94676 100644 --- a/generate-hook-docs.php +++ b/generate-hook-docs.php @@ -25,13 +25,6 @@ class HookDocsGenerator */ protected const SEARCH_INDEX_PATH = 'build/api/js/searchIndex.js'; - /** - * List of files found. - * - * @var array - */ - protected static $found_files = []; - /** * Get files to scan. * From 100097c2da0bf68e41159e0e6fa59bea84ca9bf6 Mon Sep 17 00:00:00 2001 From: piinthecloud Date: Wed, 23 Jul 2025 14:40:06 +0200 Subject: [PATCH 3/5] add new line at EOF --- run-local.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/run-local.sh b/run-local.sh index 2b17d07b43..9c40b1d486 100755 --- a/run-local.sh +++ b/run-local.sh @@ -85,4 +85,4 @@ echo "Press Ctrl+C to stop the server" echo "" # Start PHP development server -php -S localhost:8000 -t build/api \ No newline at end of file +php -S localhost:8000 -t build/api From bd9b073b05543a0ca46e41522eb52c33e7319bba Mon Sep 17 00:00:00 2001 From: piinthecloud Date: Thu, 24 Jul 2025 16:38:29 +0200 Subject: [PATCH 4/5] swap symlinking for copying in the run-build script --- run-local.sh | 59 +++++++++++++++++++++++++++++----------------------- 1 file changed, 33 insertions(+), 26 deletions(-) diff --git a/run-local.sh b/run-local.sh index 9c40b1d486..87846af063 100755 --- a/run-local.sh +++ b/run-local.sh @@ -22,36 +22,45 @@ if [ ! -d "vendor" ]; then composer install fi -# Prompt user for WooCommerce directory -echo "๐Ÿ“ Please provide the path to your WooCommerce directory." -echo "Example: /Users/YourUserName/woocommerce/plugins/woocommerce" -echo "" - -# Read user input with a default suggestion -read -p "Enter WooCommerce directory path: " WOOCOMMERCE_DIR - - -# Check if directory exists -if [ ! -d "$WOOCOMMERCE_DIR" ]; then - echo "โŒ WooCommerce plugin directory not found at: $WOOCOMMERCE_DIR" - echo " Please check the path and try again." - exit 1 +# Check if woocommerce directory exists in current directory +if [ -d "woocommerce" ]; then + echo "๐Ÿ“ Found existing woocommerce directory in current project." + WOOCOMMERCE_DIR="woocommerce" +else + # Prompt user for WooCommerce directory + echo "๐Ÿ“ Please provide the path to your WooCommerce directory." + echo "Example: /Users/YourUserName/woocommerce/plugins/woocommerce" + echo "" + read -p "Enter WooCommerce directory path: " WOOCOMMERCE_DIR + + # Check if directory exists + if [ ! -d "$WOOCOMMERCE_DIR" ]; then + echo "โŒ WooCommerce plugin directory not found at: $WOOCOMMERCE_DIR" + echo " Please check the path and try again." + exit 1 + fi fi echo "๐Ÿ“ Using WooCommerce plugin directory: $WOOCOMMERCE_DIR" -# Create symbolic link to the WooCommerce directory -if [ -L "woocommerce" ]; then - echo "๐Ÿ”— Removing existing symbolic link..." - rm woocommerce -elif [ -d "woocommerce" ]; then - echo "๐Ÿ—‘๏ธ Removing existing woocommerce directory..." - rm -rf woocommerce +# Only copy files if we're using an external path (not the existing woocommerce directory) +if [ "$WOOCOMMERCE_DIR" != "woocommerce" ]; then + if [ -d "woocommerce" ]; then + echo "๐Ÿ—‘๏ธ Removing existing woocommerce directory..." + rm -rf woocommerce + fi + + echo "๐Ÿ“ Copying WooCommerce files..." + mkdir -p woocommerce + + # Copy only the directories we want for documentation + cp -r "$WOOCOMMERCE_DIR"/includes woocommerce/ 2>/dev/null || true + cp -r "$WOOCOMMERCE_DIR"/src woocommerce/ 2>/dev/null || true + cp -r "$WOOCOMMERCE_DIR"/templates woocommerce/ 2>/dev/null || true +else + echo "๐Ÿ“ Using existing woocommerce directory in project." fi -echo "๐Ÿ”— Creating symbolic link to local WooCommerce plugin directory..." -ln -s "$WOOCOMMERCE_DIR" woocommerce - # Clean up any existing build if [ -d "build" ]; then echo "๐Ÿงน Cleaning up existing build..." @@ -74,8 +83,6 @@ php generate-hook-docs.php echo "" echo "โœ… Documentation generated successfully!" echo "๐Ÿ“ Output location: ./build/api/" -echo "๐Ÿ”— The symbolic link to your WooCommerce directory will remain for future builds." -echo " To remove it: rm woocommerce" echo "" echo "๐ŸŒ Starting local web server for WooCommerce Code Reference..." echo "๐Ÿ“ Serving from: ./build/api" From 8b9f13b1775d932a4e7112794c46a193251dfb3b Mon Sep 17 00:00:00 2001 From: piinthecloud Date: Fri, 25 Jul 2025 12:20:52 +0200 Subject: [PATCH 5/5] address pr comments --- run-local.sh | 54 ++++++++++++++++++++++++++-------------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/run-local.sh b/run-local.sh index 87846af063..272b3ff3ac 100755 --- a/run-local.sh +++ b/run-local.sh @@ -1,8 +1,16 @@ #!/usr/bin/env bash set -o errexit # Abort if any command fails +# Change to the script's directory for safety +cd "$(dirname "$0")" + echo "๐Ÿš€ WooCommerce Code Reference Generator - Local Development" echo "==========================================================" +echo "" +echo "Usage: ./run-local.sh [source-directory]" +echo " - If source-directory is provided, use that as WooCommerce source" +echo " - If no argument provided, use ./woocommerce if it exists, otherwise prompt" +echo "" # Check if PHP is available if ! command -v php &> /dev/null; then @@ -22,29 +30,35 @@ if [ ! -d "vendor" ]; then composer install fi -# Check if woocommerce directory exists in current directory -if [ -d "woocommerce" ]; then - echo "๐Ÿ“ Found existing woocommerce directory in current project." +# Determine WooCommerce directory +if [ $# -eq 1 ]; then + # Use provided source directory + WOOCOMMERCE_DIR="$1" + echo "๐Ÿ“ Using provided source directory: $WOOCOMMERCE_DIR" +elif [ -d "woocommerce" ]; then + # Use existing woocommerce directory in current project WOOCOMMERCE_DIR="woocommerce" + echo "๐Ÿ“ Found existing woocommerce directory in current project." else # Prompt user for WooCommerce directory echo "๐Ÿ“ Please provide the path to your WooCommerce directory." echo "Example: /Users/YourUserName/woocommerce/plugins/woocommerce" echo "" read -p "Enter WooCommerce directory path: " WOOCOMMERCE_DIR +fi - # Check if directory exists - if [ ! -d "$WOOCOMMERCE_DIR" ]; then - echo "โŒ WooCommerce plugin directory not found at: $WOOCOMMERCE_DIR" - echo " Please check the path and try again." - exit 1 - fi +# Check if directory exists +if [ ! -d "$WOOCOMMERCE_DIR" ]; then + echo "โŒ WooCommerce plugin directory not found at: $WOOCOMMERCE_DIR" + echo " Please check the path and try again." + exit 1 fi echo "๐Ÿ“ Using WooCommerce plugin directory: $WOOCOMMERCE_DIR" -# Only copy files if we're using an external path (not the existing woocommerce directory) +# Copy files if we're using an external path (not the existing woocommerce directory) if [ "$WOOCOMMERCE_DIR" != "woocommerce" ]; then + # Always remove existing woocommerce directory when using external source if [ -d "woocommerce" ]; then echo "๐Ÿ—‘๏ธ Removing existing woocommerce directory..." rm -rf woocommerce @@ -61,24 +75,10 @@ else echo "๐Ÿ“ Using existing woocommerce directory in project." fi -# Clean up any existing build -if [ -d "build" ]; then - echo "๐Ÿงน Cleaning up existing build..." - rm -rf build -fi - +# Generate documentation echo "๐Ÿ”ง Generating documentation from local WooCommerce source..." echo "" - -# Run PHPDocumentor directly with the local source -./vendor/bin/phpdoc run \ - --template="data/templates/woocommerce" \ - --sourcecode \ - --defaultpackagename="WooCommerce" - -# Generate hook documentation AFTER PHPDocumentor completes -echo "๐Ÿ”ง Generating hook documentation..." -php generate-hook-docs.php +./deploy.sh --no-download --build-only --source-version 0.0.0 echo "" echo "โœ… Documentation generated successfully!" @@ -92,4 +92,4 @@ echo "Press Ctrl+C to stop the server" echo "" # Start PHP development server -php -S localhost:8000 -t build/api +php -S localhost:8000 -t build/api