Stop Writing README Files by Hand: Auto-Generate API Docs on Every Merge

Every engineering team has the same README problem.

Someone writes a great README when the project launches. Six months later, the API has changed in three places but the docs haven't. New developers onboard with incorrect examples. API consumers hit endpoints that no longer exist. And nobody wants to be the person who has to sit down and manually rewrite the documentation.

The traditional answer is "just update the docs when you change the code." The actual behavior is: docs drift.

There's a better approach: treat documentation as a build artifact, not a manual deliverable.

The Pattern: Docs as CI Output

The same way you run tests on every PR and generate coverage reports on every merge, you can generate documentation automatically. The key insight is that your codebase already contains everything needed to produce accurate docs — function signatures, module structure, exports, route handlers. An AI model can read that structure and produce documentation that reflects what the code actually does, not what someone wrote about it six months ago.

Here's how to wire this up in a GitHub Actions workflow.

Setup: Two Files, Five Minutes

You'll need a RapidAPI key with access to the Code Documentation Generator API. The free tier handles small repos comfortably.

Step 1: Add your RapidAPI key as a secret

In your repo: Settings → Secrets and variables → Actions → New repository secret

Name: RAPID_API_KEY

Step 2: Create .github/workflows/docs.yml

name: Generate Documentation

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4

      - name: Generate full documentation
        uses: peaklineops/code-docs-action@v1
        with:
          repo_url: https://github.com/${{ github.repository }}
          doc_type: full
          output_file: docs/API.md
          rapid_api_key: ${{ secrets.RAPID_API_KEY }}

      - name: Commit updated docs
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add docs/API.md
          git diff --staged --quiet || git commit -m "docs: auto-update API documentation [skip ci]"
          git push

That's it. Every time you push to main, the action:

1. Fetches your repo's source files
2. Sends them to the documentation API
3. Gets back structured markdown docs
4. Commits the result back to your repo

The [skip ci] tag prevents the commit from triggering another docs run.

Three Doc Types

The action supports three modes via the doc_type parameter:

readme — Generates a full project README: what it does, installation, usage, examples. Good for public repos where the README is the first thing people read.

api-reference — Generates a structured API reference: all endpoints/functions with parameters, return types, and examples. Good for libraries and REST APIs.

full — Combines both. A complete README plus detailed API reference in a single document.

Selective Documentation

If you only want to regenerate docs when source files change (not on every push), use path filtering:

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'lib/**'
      - '*.ts'
      - '*.js'
      - '*.py'

This skips the doc generation step when only tests, config files, or existing docs change — no unnecessary API calls.

Splitting README from API Reference

For larger projects, you may want to keep your README human-authored (for tone and positioning) but auto-generate the technical API reference:

    steps:
      - uses: actions/checkout@v4

      - name: Generate API reference only
        uses: peaklineops/code-docs-action@v1
        with:
          repo_url: https://github.com/${{ github.repository }}
          doc_type: api-reference
          output_file: docs/API_REFERENCE.md
          rapid_api_key: ${{ secrets.RAPID_API_KEY }}

This gives you a consistently-updated docs/API_REFERENCE.md while leaving your README.md under human control.

The Result

After the first run, you'll have a docs/API.md (or wherever you pointed output_file) that reflects the current state of your codebase. It updates automatically on every merge to main. New team members get accurate docs on day one. API consumers don't hit deprecated endpoints.

The documentation debt stops accumulating.

---

The Code Documentation Generator API is available on RapidAPI. The GitHub Action is at peaklineops/code-docs-action. Free tier: 5 requests/day. Pro: $9/mo for 100 requests/day.