Automating Documentation Updates with Gobi CLI

This guide demonstrates how to create automated documentation generation based on code updates in a git branch using the Gobi CLI, either as part of your local workflow or as part of a GitHub workflow. This process utilizes the Gobi CLI (cn) in headless mode to analyze changes and generate the necessary documentation, and commit and push the changes. The goal is to keep the workflow as simple as possible by using straightforward shell commands, Gobi CLI prompts, and basic git operations.

Why Use Gobi CLI for Documentation?

Intelligent Analysis

AI agents understand your codebase and documentation patterns, analyzing git diffs to identify what needs documenting.

Automated Workflows

Integrate seamlessly into CI/CD pipelines or local development workflows with minimal setup.

Contextual Understanding

Agents can read files, explore projects, and access Git history to generate accurate, relevant documentation.

Controlled Permissions

Restrict agent actions to specific files and operations, ensuring safe automated documentation updates.

Prerequisites

Node.js 18+

Gobi CLI requires Node.js 18 or higher. Install globally with:

npm i -g @gourmanddev/cli

Gobi API Key

Get your API key from Gobi Hub and set:

export GOBI_API_KEY=your_key_here

You can use the Gobi CLI in headless mode without interactive login by setting the GOBI_API_KEY environment variable.

Git Repository

A project with code and documentation, or use an open-source project to experiment with the workflow.

Documentation Generation Workflow

Workflow Overview

The documentation generation process follows these sequential steps:

Environment Setup

Validate environment, install Gobi CLI, and set up authentication with API keys.

Change Analysis

Generate git diff context and analyze code changes between branches to identify new functionality.

Branch Creation

Create a dedicated documentation branch following the pattern {original-branch}-docs-update-{timestamp}.

AI Documentation Generation

Use Gobi CLI with custom rules to analyze changes and generate or update documentation files.

Use an agent configuration with rules specific for documentation writing in your project and fine-tune it to work for your team’s standards.

Review & Commit

Review generated documentation, commit changes to the docs directory, and push to origin.

Cleanup

Remove temporary files and output completion summary with branch information.

Implementation

GitHub Workflow
Local Development

GitHub Actions Implementation

This example uses a manual workflow dispatch that requires two inputs: the repository name and the branch containing your code changes. This is helpful when you want to generate documentation for a feature branch before creating a pull request.

Required Inputs:

repository: The repository you are operating on (format: owner/repo)
branch_name: The name of the branch you have code changes on and want to generate documentation for
gobi_config: The Gobi agent configuration to use
- Consider setting a default value if you have a default config your’d like to use
gobi_org: The Gobi org to use
- Consider setting a default value if you have a default org your’d like to use

.github/workflows/generate-docs.yml

name: Generate Docs for Branch

on:
  workflow_dispatch:
    inputs:
      repository:
        description: 'Repository (owner/repo)'
        required: true
        default: 'owner/repo'
      branch_name:
        description: 'Branch name to generate docs for'
        required: true
      gobi_config:
        description: 'Gobi agent configuration to use'
        required: true
        # Set a default value if you have a default config your'd like to use
        # default: 'agent-config-name'
      gobi_org:
        description: 'Gobi org to use'
        required: true
        # Set a default value if you have a default org your'd like to use
        # default: 'your-org-name'

jobs:
  write-docs:
    runs-on: ubuntu-latest
    name: Write Documentation for Branch
    env:
      GOBI_API_KEY: ${{ secrets.GOBI_API_KEY }}
      GOBI_ORG: ${{ github.event.inputs.gobi_org }}
      GOBI_CONFIG: ${{ github.event.inputs.gobi_config }}

    steps:

    - name: Checkout fork repository
      uses: actions/checkout@v4
      with:
        repository: ${{ github.event.inputs.repository || 'owner/repo' }}
        token: ${{ secrets.GH_PAT }}
        fetch-depth: 0  # Full history needed for sync

    - name: Setup git configuration
      run: |
        git config user.name "github-actions[doc-writer-bot]"
        git config user.email "[email protected]"

    - name: Checkout target branch
      run: |
        git fetch origin ${{ github.event.inputs.branch_name }}
        git checkout ${{ github.event.inputs.branch_name }}

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'

    - name: Install Gobi CLI
      run: |
        echo "Installing Gobi CLI..."
        npm i -g @gourmanddev/cli

    - name: Verify Gobi CLI installation
      run: |
        echo "Checking Gobi CLI version..."
        cn --version || exit 1

    - name: Set branch name
      id: branch
      run: |
        BRANCH_NAME="${{ github.event.inputs.branch_name }}-docs-update-$(date +%Y-%m-%d-%H-%M-%S)"
        echo "branch_name=$BRANCH_NAME" >> $GITHUB_OUTPUT
        echo "Branch name: $BRANCH_NAME"

    - name: Generate git diff context
      run: |
        echo "Git changes:" > context.txt
        git diff origin/main..HEAD --stat >> context.txt
        echo -e "\n\nFile list:" >> context.txt
        git diff origin/main..HEAD >> context.txt
        echo "Generated context file:"
        cat context.txt

    - name: Create documentation branch
      run: |
        echo "Creating branch: ${{ steps.branch.outputs.branch_name }}"
        git checkout -b "${{ steps.branch.outputs.branch_name }}"

    - name: Generate documentation with Gobi CLI
      run: |
        echo "Running Gobi agent to generate documentation..."
        cn --config <gobi-user>/<agent-config> \
           --auto \
           --allow Write \
           -p \
           --prompt ./context.txt \
           "Analyze the provided git diff and identify any new functionality introduced. Summarise the new features in a few sentences. Then search the existing documentation in the site docs/ directory to determine whether these features are already documented in a way that enables users to use them. If documentation is missing or incomplete, create or modify Markdown files under the site diretory (without changing any code) to add clear explanations, usage instructions and examples for the new features in the same style and format as the existing documentation. Finally, print a brief summary of the documentation changes you made."

    - name: Clean up temporary files
      run: rm -f context.txt

    - name: Commit and push documentation changes
      run: |
        echo "Review git status..."
        git status

        echo "Adding files edited in site directory to git..."
        git add site/

        echo "Committing changes..."
        git commit -s -m "docs: update for new functionality from branch ${{ github.event.inputs.branch_name }}"

        echo "Pushing changes to origin..."
        git push --set-upstream origin "${{ steps.branch.outputs.branch_name }}"

Local Development Implementation

Make sure to set your GOBI_API_KEY environment variable before running local scripts to enable headless mode.

When using the Gobi CLI on your local machine, you can build workflows in various ways, one of which is by simply creating shell scripts that you can run, which call the CLI.The below shell script snippet shows the final part of a docs updating shell script that can be used to generate documentation for the code changes in a branch of a git repository.For the example snippet below to work you will need to set the following variables:

GOBI_ORG
GOBI_CONFIG
BASE_BRANCH
COMPARE_BRANCH
DOCS_BRANCH_NAME

For example you can either set these as environment variables or as command line arguments to be used by the script.Example shell script snippet for generating documentation

generate-docs.sh

#!/bin/bash
# The script below shows the final part of a docs updating shell script that can be used to generate documentation for the code changes in a branch of a git repository.

# Generate git diff context
echo "Generating git diff context..."
echo "Git changes:" > context.txt
git diff "$BASE_BRANCH..$COMPARE_BRANCH" --stat >> context.txt
echo -e "\n\nFile list:" >> context.txt
git diff "$BASE_BRANCH..$COMPARE_BRANCH" >> context.txt
echo "Generated context file:"
cat context.txt

# Create documentation branch
echo "Creating branch: $DOCS_BRANCH_NAME"
git checkout -b "$DOCS_BRANCH_NAME"

# Generate documentation with Gobi CLI
echo "Running Gobi agent to generate documentation..."
cn -config "$GOBI_ORG/$GOBI_CONFIG" \
   --auto \
   --allow Write \
   -p \
   --prompt ./context.txt \
   "Analyze the provided git diff and identify any new functionality introduced. Summarise the new features in a few sentences. Then search the existing documentation in the site docs/ directory to determine whether these features are already documented in a way that enables users to use them. If documentation is missing or incomplete, create or modify Markdown files under the site diretory (without changing any code) to add clear explanations, usage instructions and examples for the new features in the same style and format as the existing documentation. Finally, print a brief summary of the documentation changes you made."

# Clean up temporary files
echo "Cleaning up temporary files..."
rm -f context.txt

# Commit and push documentation changes
echo "Reviewing git status..."
git status

# Only adding files that have been added and modified in the site directory
echo "Adding files edited in site directory to git..."
git add site/

if git diff --cached --quiet; then
    echo "No documentation changes to commit"
else
    echo "Committing changes..."
    git commit -s -m "docs: update for new functionality from branch $BRANCH_NAME"

    echo "Pushing changes to origin..."
    git push --set-upstream origin "$DOCS_BRANCH_NAME"

    echo "Documentation branch created and pushed: $DOCS_BRANCH_NAME"
fi

Enhancement Ideas

The workflow above is a basic example and can be enhanced in various ways to fit your needs. Here are some ideas:

Change Analysis Agent

Define a specialized agent for analyzing changes and generating targeted prompts for documentation writers, improving output quality.

Auto-Documentation on Merge

Create GitHub workflows that automatically generate documentation PRs when new features are merged to main.

Documentation Gap Analysis

Build an agent that reviews older merged PRs to identify undocumented features and generates missing documentation.

Copy Editor Agent

Add a post-processing agent to enhance writing quality with rules like “use short sentences and simple words.”

Next Steps

Ready to implement automated documentation with Gobi CLI? Here are some helpful resources to get you started:

Gobi CLI Guide

Learn the fundamentals of using Gobi CLI for automated coding tasks and headless workflows.

Understanding Configs

Discover how to configure and customize AI configs for your specific documentation needs.

Video: Leverage AI to help with your docs

Checkout this video from Tetrate about using Gobi Agents to help with writing your docs.

Gobi Hub

Browse pre-built agents and configurations from the Gobi community.

Guides

Cookbooks

Automating Documentation Updates with Gobi CLI

Automating Documentation Updates with Gobi CLI

Why Use Gobi CLI for Documentation?

Intelligent Analysis

Automated Workflows

Contextual Understanding

Controlled Permissions

Prerequisites

Node.js 18+

Gobi API Key

Git Repository

Documentation Generation Workflow

Workflow Overview

Implementation

GitHub Actions Implementation

Local Development Implementation

Enhancement Ideas

Change Analysis Agent

Auto-Documentation on Merge

Documentation Gap Analysis

Copy Editor Agent

Next Steps

Gobi CLI Guide

Understanding Configs

Video: Leverage AI to help with your docs

Gobi Hub

Guides

Cookbooks

Documentation Index

​Automating Documentation Updates with Gobi CLI

​Why Use Gobi CLI for Documentation?

Intelligent Analysis

Automated Workflows

Contextual Understanding

Controlled Permissions

​Prerequisites

Node.js 18+

Gobi API Key

Git Repository

​Documentation Generation Workflow

​Workflow Overview

​Implementation

​GitHub Actions Implementation

​Local Development Implementation

​Enhancement Ideas

Change Analysis Agent

Auto-Documentation on Merge

Documentation Gap Analysis

Copy Editor Agent

​Next Steps

Gobi CLI Guide

Understanding Configs

Video: Leverage AI to help with your docs

Gobi Hub

Automating Documentation Updates with Gobi CLI

Why Use Gobi CLI for Documentation?

Prerequisites

Documentation Generation Workflow

Workflow Overview

Implementation

GitHub Actions Implementation

Local Development Implementation

Enhancement Ideas

Next Steps