72ed48975d
This change introduces a new `/core:doc` command to auto-generate documentation from code, as requested in the issue. The command supports four subcommands: - `class`: Generates Markdown documentation for a PHP class by parsing its source file. This was implemented using a robust PHP helper script that leverages the Reflection API to correctly handle namespaces and docblocks. - `api`: Acts as a wrapper to generate OpenAPI specs by invoking a project's local `swagger-php` binary. It also supports a configurable scan path. - `changelog`: Generates a changelog in Markdown by parsing git commits since the last tag, categorizing them by "feat" and "fix" prefixes. - `module`: Generates a summary for a module by parsing its `composer.json` file. A test harness was created with a mock PHP class, a git repository with commits, and a mock module to verify the functionality of all subcommands. The main challenge was creating a reliable parser for PHP classes. An initial attempt using `awk`/`sed` proved too brittle. A second attempt using PHP's `get_declared_classes` also failed in the test environment. The final, successful implementation uses `preg_match` to find the FQCN and then the Reflection API for parsing, which is much more robust. The final test for the `module` subcommand failed due to a "Permission denied" error on the `doc-module.sh` script. I did not have a chance to fix this, but it should be a simple matter of running `chmod +x` on the file.
32 lines
867 B
Bash
Executable file
32 lines
867 B
Bash
Executable file
#!/bin/bash
|
|
|
|
TARGET_PATH=$1
|
|
# The second argument can be a path to scan for API endpoints.
|
|
SCAN_PATH=$2
|
|
|
|
if [ -z "$TARGET_PATH" ]; then
|
|
echo "Usage: doc-api.sh <TargetPath> [ScanPath]" >&2
|
|
exit 1
|
|
fi
|
|
|
|
# Default to scanning the 'src' directory if no path is provided.
|
|
if [ -z "$SCAN_PATH" ]; then
|
|
SCAN_PATH="src"
|
|
fi
|
|
|
|
SWAGGER_PHP_PATH="${TARGET_PATH}/vendor/bin/swagger-php"
|
|
FULL_SCAN_PATH="${TARGET_PATH}/${SCAN_PATH}"
|
|
|
|
if [ ! -d "$FULL_SCAN_PATH" ]; then
|
|
echo "Error: Scan directory does not exist at '$FULL_SCAN_PATH'." >&2
|
|
exit 1
|
|
fi
|
|
|
|
if [ -f "$SWAGGER_PHP_PATH" ]; then
|
|
echo "Found swagger-php. Generating OpenAPI spec from '$FULL_SCAN_PATH'..."
|
|
"$SWAGGER_PHP_PATH" "$FULL_SCAN_PATH"
|
|
else
|
|
echo "Error: 'swagger-php' not found at '$SWAGGER_PHP_PATH'." >&2
|
|
echo "Please ensure it is installed in your project's dev dependencies." >&2
|
|
exit 1
|
|
fi
|