Penify

Appearance

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 ​

bash
penify docgen

By default, this command:

  • Analyzes the current Git diff (changes since last commit)
  • Generates documentation for changed files only
  • Requires authentication via penify login

Command Options ​

-l, --location ​

Specify a target for documentation generation:

bash
# Generate documentation for a specific file
penify docgen -l path/to/file.py

# Generate documentation for a specific folder
penify 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:

bash
penify docgen install-hook

uninstall-hook ​

Remove the Git post-commit hook:

bash
penify docgen uninstall-hook

Option Combinations ​

Generate Documentation for Current Git Diff ​

bash
# Basic usage - current Git diff
penify docgen

Generate Documentation for a Specific File ​

bash
# Single file documentation
penify docgen -l src/main.py

Generate Documentation for a Folder ​

bash
# Folder documentation
penify docgen -l src/models/

Install Hook in Current Repository ​

bash
# Install hook in current Git repository
penify docgen install-hook

Install Hook in Specific Repository ​

bash
# Install hook in a specific Git repository
penify docgen install-hook -l /path/to/repo

Uninstall Hook from Current Repository ​

bash
# Uninstall hook from current Git repository
penify docgen uninstall-hook

Uninstall Hook from Specific Repository ​

bash
# Uninstall hook from a specific Git repository
penify 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 penify docgen install-hook, Penify:

  1. Creates a post-commit hook script in the .git/hooks directory
  2. Makes the script executable
  3. Configures the hook to run penify docgen after each commit

Hook Script Content ​

The generated post-commit hook contains:

bash
#!/bin/sh
# This is a post-commit hook generated by penify.
# Automatically generates documentation for changed files after each commit.

penify 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:

bash
penify docgen install-hook -l /path/to/repo

Installation Requirements ​

To install hooks, you need:

  • A valid Penify API token (login first with penify login)
  • Write permissions to the .git/hooks directory

Verifying Installation ​

After installation, you can verify that the hook is installed:

bash
cat .git/hooks/post-commit

Hook Customization ​

You can customize the post-commit hook after installation:

Modifying Hook Behavior ​

  1. Edit the .git/hooks/post-commit file
  2. Add additional options to the penify docgen command
  3. Add other commands to run after commit

Example of a customized hook:

bash
#!/bin/sh
# This is a post-commit hook generated by penify.
# Automatically generates documentation for changed files after each commit.

# Generate documentation
penify docgen -gf /path/to/git/repository -t your_api_token

# Additional custom commands
echo "Documentation generation complete!"

Advanced Hook Scenarios ​

Conditional Documentation Generation:

bash
#!/bin/sh
# Only generate documentation for commits to the main branch
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [ "$BRANCH" = "main" ]; then
  penify docgen -gf /path/to/git/repository -t your_api_token
fi

Documenting Specific Files/Folders:

bash
#!/bin/sh
# Only document Python files in the src directory
penify docgen -l src/ -gf /path/to/git/repository -t your_api_token

Hook Uninstallation ​

Standard Uninstallation ​

To remove a hook from the current repository:

bash
penify docgen uninstall-hook

Specific Repository Uninstallation ​

To remove a hook from a specific repository:

bash
penify docgen uninstall-hook -l /path/to/repo

Manual Hook Removal ​

If needed, you can manually remove the hook:

bash
rm .git/hooks/post-commit

Verifying Uninstallation ​

Check that the hook was successfully removed:

bash
ls -la .git/hooks/post-commit  # Should return "No such file or directory"

Advanced Use Cases ​

Continuous Integration ​

Run documentation generation in CI pipelines:

bash
# In your CI script
export PENIFY_API_TOKEN=your_api_token
penify docgen -l src/

Batch Documentation ​

Generate documentation for multiple repositories:

bash
# Bash script for batch documentation
for repo in repo1 repo2 repo3; do
  cd /path/to/$repo
  penify docgen -l .
done

Custom Git Hook Integration ​

Integrate with other Git hooks:

bash
# In .git/hooks/pre-push
penify docgen -l src/

Documenting Release Tags ​

Generate documentation when creating a release tag:

bash
# Document everything when creating a tag
git tag -a v1.0.0
penify docgen -l .  # Document entire codebase
git commit --amend -m "Release v1.0.0 with updated documentation"

Troubleshooting ​

Common Issues ​

  1. "Authentication required"

    • Run penify login before using documentation features
    • Check your API token with cat ~/.penify

  2. "Permission denied when installing hook"

    • Check Git repository permissions
    • Try running with sudo (if appropriate for your environment)
    • Ensure the .git/hooks directory exists

  3. "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

  4. "File or directory not found"

    • Verify the path provided to the -l option
    • Ensure you're running the command from the correct directory

  5. "Hook uninstallation failed"

    • Check permissions on the .git/hooks directory
    • Try manual removal: rm .git/hooks/post-commit

Debugging ​

For detailed output when running documentation commands:

bash
export PENIFY_DEBUG=1
penify docgen -l src/

Getting Help ​

For command-specific help:

bash
penify docgen --help
penify docgen install-hook --help
penify docgen uninstall-hook --help

Copyright © 2023 Snorkell Associates and Co