Advanced Usage

This section covers advanced usage scenarios and options for qmims, allowing you to customize and optimize your documentation workflow.

Dry Run Mode

Dry run mode shows what would be done without making any actual changes. This is useful for previewing changes before applying them.

qmims generate --dry-run
qmims edit --dry-run

In dry run mode, qmims will analyze your project, process instructions, and show the content that would be generated, but it won't write any files.

Verbose Output

Verbose mode provides detailed output for debugging:

qmims generate --verbose
qmims edit --verbose

This will show:

• Command execution details
• Amazon Q interactions
• File operations
• Error messages with stack traces

Force Overwrite

Force mode overwrites existing files without prompting:

qmims generate --force

Automatic Approval

The --yes flag automatically approves all permission requests:

qmims generate --yes
qmims edit --yes

This is useful for scripting or automation, but should be used with caution as it will apply all changes without confirmation.

Custom Output Path

You can specify a custom output filename:

qmims generate --output docs/DOCUMENTATION.md

This allows you to generate documentation in a specific location or with a different filename than the default README.md.

Combining Options

Options can be combined for more complex operations:

qmims generate --mode template:library --output API.md --force --verbose

Environment Variables

You can use environment variables to override configuration settings. This is useful for CI/CD pipelines or when you want to temporarily change a setting.

# Linux/macOS
QMIMS_DEFAULTS_MODE=template QMIMS_DEFAULTS_TEMPLATE_NAME=minimal qmims generate

# Windows (PowerShell)
$env:QMIMS_DEFAULTS_MODE="template"; $env:QMIMS_DEFAULTS_TEMPLATE_NAME="minimal"; qmims generate

Environment variables follow this naming convention:

• Prefix: QMIMS_
• Configuration key with dots replaced by underscores and converted to uppercase

For example:

• defaults.mode becomes QMIMS_DEFAULTS_MODE
• q.autoApproveEdits becomes QMIMS_Q_AUTO_APPROVE_EDITS

Git Integration

qmims can automatically commit changes to git if you enable the git.autoCommit setting:

qmims config set git.autoCommit true
qmims config set git.commitMessageFormat "docs: update README.md using qmims"

With these settings, qmims will automatically commit changes to git after generating or editing a README file.

CI/CD Integration

You can integrate qmims into your CI/CD pipeline to automatically generate or update documentation when your code changes.

GitHub Actions Example

name: Update Documentation

on:
  push:
    branches: [ main ]
    paths:
      - 'src/**'
      - 'package.json'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install Amazon Q CLI
        run: npm install -g @aws/amazon-q-cli
      - name: Login to Amazon Q
        run: q login --token ${{ secrets.Q_TOKEN }}
      - name: Install qmims
        run: npm install -g qmims
      - name: Update README
        run: qmims generate --force --yes
      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: "docs: update README.md using qmims"

Scripting with qmims

You can create scripts to automate documentation tasks with qmims. Here's an example shell script that updates documentation for multiple projects:

#!/bin/bash

# Update documentation for multiple projects
projects=("project1" "project2" "project3")

for project in "${projects[@]}"; do
  echo "Updating documentation for $project"
  cd "$project" || continue
  qmims generate --force --yes
  cd ..
done

echo "Documentation update complete"