Penify CLI - Documentation Generation Commands
This document provides a detailed guide to all permutations and combinations of the docgen
command, including extensive information about Git hook commands for automating documentation generation.
Table of Contents
Basic Usage
penifycli docgen
By default, this command:
- Analyzes the current Git diff (changes since last commit)
- Generates documentation for changed files only
- Requires authentication via
penifycli login
Command Options
-l, --location
Specify a target for documentation generation:
# Generate documentation for a specific file
penifycli docgen -l path/to/file.py
# Generate documentation for a specific folder
penifycli docgen -l path/to/folder
Without this flag, Penify analyzes only Git-tracked modified files.
Subcommands
install-hook
Install a Git post-commit hook to automatically generate documentation:
penifycli docgen install-hook
uninstall-hook
Remove the Git post-commit hook:
penifycli docgen uninstall-hook
Option Combinations
Generate Documentation for Current Git Diff
# Basic usage - current Git diff
penifycli docgen
Generate Documentation for a Specific File
# Single file documentation
penifycli docgen -l src/main.py
Generate Documentation for a Folder
# Folder documentation
penifycli docgen -l src/models/
Install Hook in Current Repository
# Install hook in current Git repository
penifycli docgen install-hook
Install Hook in Specific Repository
# Install hook in a specific Git repository
penifycli docgen install-hook -l /path/to/repo
Uninstall Hook from Current Repository
# Uninstall hook from current Git repository
penifycli docgen uninstall-hook
Uninstall Hook from Specific Repository
# Uninstall hook from a specific Git repository
penifycli docgen uninstall-hook -l /path/to/repo
Git Hook Commands
Penify provides Git hook commands to automate documentation generation as part of your Git workflow.
Hook Installation
How Hooks Work
When you install a Git hook with penifycli docgen install-hook
, Penify:
- Creates a post-commit hook script in the
.git/hooks
directory - Makes the script executable
- Configures the hook to run
penifycli docgen
after each commit
Hook Script Content
The generated post-commit hook contains:
#!/bin/sh
# This is a post-commit hook generated by penifycli.
# Automatically generates documentation for changed files after each commit.
penifycli docgen -gf /path/to/git/repository -t your_api_token
Installation Location
By default, hooks are installed in the current Git repository. You can specify a different location:
penifycli docgen install-hook -l /path/to/repo
Installation Requirements
To install hooks, you need:
- A valid Penify API token (login first with
penifycli login
) - Write permissions to the
.git/hooks
directory
Verifying Installation
After installation, you can verify that the hook is installed:
cat .git/hooks/post-commit
Hook Customization
You can customize the post-commit hook after installation:
Modifying Hook Behavior
- Edit the
.git/hooks/post-commit
file - Add additional options to the
penifycli docgen
command - Add other commands to run after commit
Example of a customized hook:
#!/bin/sh
# This is a post-commit hook generated by penifycli.
# Automatically generates documentation for changed files after each commit.
# Generate documentation
penifycli docgen -gf /path/to/git/repository -t your_api_token
# Additional custom commands
echo "Documentation generation complete!"
Advanced Hook Scenarios
Conditional Documentation Generation:
#!/bin/sh
# Only generate documentation for commits to the main branch
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [ "$BRANCH" = "main" ]; then
penifycli docgen -gf /path/to/git/repository -t your_api_token
fi
Documenting Specific Files/Folders:
#!/bin/sh
# Only document Python files in the src directory
penifycli docgen -l src/ -gf /path/to/git/repository -t your_api_token
Hook Uninstallation
Standard Uninstallation
To remove a hook from the current repository:
penifycli docgen uninstall-hook
Specific Repository Uninstallation
To remove a hook from a specific repository:
penifycli docgen uninstall-hook -l /path/to/repo
Manual Hook Removal
If needed, you can manually remove the hook:
rm .git/hooks/post-commit
Verifying Uninstallation
Check that the hook was successfully removed:
ls -la .git/hooks/post-commit # Should return "No such file or directory"
Advanced Use Cases
Continuous Integration
Run documentation generation in CI pipelines:
# In your CI script
export PENIFY_API_TOKEN=your_api_token
penifycli docgen -l src/
Batch Documentation
Generate documentation for multiple repositories:
# Bash script for batch documentation
for repo in repo1 repo2 repo3; do
cd /path/to/$repo
penifycli docgen -l .
done
Custom Git Hook Integration
Integrate with other Git hooks:
# In .git/hooks/pre-push
penifycli docgen -l src/
Documenting Release Tags
Generate documentation when creating a release tag:
# Document everything when creating a tag
git tag -a v1.0.0
penifycli docgen -l . # Document entire codebase
git commit --amend -m "Release v1.0.0 with updated documentation"
Troubleshooting
Common Issues
"Authentication required"
- Run
penifycli login
before using documentation features - Check your API token with
cat ~/.penify
- Run
"Permission denied when installing hook"
- Check Git repository permissions
- Try running with sudo (if appropriate for your environment)
- Ensure the
.git/hooks
directory exists
"Hook installed but not running"
- Check if the hook is executable:
ls -la .git/hooks/post-commit
- Make it executable if needed:
chmod +x .git/hooks/post-commit
- Check for syntax errors in the hook script
- Check if the hook is executable:
"File or directory not found"
- Verify the path provided to the
-l
option - Ensure you're running the command from the correct directory
- Verify the path provided to the
"Hook uninstallation failed"
- Check permissions on the
.git/hooks
directory - Try manual removal:
rm .git/hooks/post-commit
- Check permissions on the
Debugging
For detailed output when running documentation commands:
export PENIFY_DEBUG=1
penifycli docgen -l src/
Getting Help
For command-specific help:
penifycli docgen --help
penifycli docgen install-hook --help
penifycli docgen uninstall-hook --help