Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
434 lines (315 loc) · 10.3 KB

DOCUMENTATION.md

File metadata and controls

434 lines (315 loc) · 10.3 KB

Documentation Automation Guide

This guide explains the automated documentation system for the Nevermined Payments SDK.

Overview

The documentation system consists of:

  • Markdown Files: LLM-friendly documentation in markdown/ directory
  • Automated Updates: GitHub Actions workflow that updates docs on push
  • Automated Publishing: GitHub Actions workflow that publishes docs on tag
  • Manual Tools: Scripts for local documentation management

Documentation Structure

markdown/
├── installation.md
├── initializing-the-library.md
├── payment-plans.md
├── agents.md
├── publishing-static-resources.md
├── payments-and-balance.md
├── querying-an-agent.md
├── validation-of-requests.md
├── mcp-integration.md
├── a2a-integration.md
├── x402.md
└── README.md

Automated Workflows

1. Update Documentation (on Push)

Trigger: Push to main or develop when source files change

What It Does:

  • Validates all documentation files exist
  • Creates a pull request with documentation updates
  • Enables auto-merge for automatic merging when checks pass

Configuration: .github/workflows/update-docs.yml

When It Runs:

# Any push that changes these paths:
src/**                     # Source code changes
tests/**                   # Test changes (new examples)
package.json               # Version updates
MINTLIFY_API_REFERENCE.md  # Documentation spec

Manual Trigger:

# Via GitHub CLI
gh workflow run update-docs.yml

# Via GitHub UI
Actions → Update Documentation → Run workflow

2. Publish Documentation (on Tag)

Trigger: Creating a new version tag (e.g., v1.0.2)

What It Does:

  • Copies all .md files from markdown/ to docs_mintlify repository
  • Creates a pull request in the docs repository
  • Enables auto-merge for automatic merging when checks pass
  • Includes version info, change summary, and automated labels

Configuration: .github/workflows/publish-docs.yml

When It Runs:

# Create and push a version tag
git tag -a v1.0.2 -m "Release v1.0.2"
git push origin v1.0.2

Manual Trigger:

# Via GitHub CLI
gh workflow run publish-docs.yml -f version=v1.0.2

# Via script
./scripts/publish-docs.sh

Manual Documentation Management

Validate Documentation

Check that all documentation files are present and valid:

./scripts/generate-docs.sh

This script:

  • Verifies all 11 .md files exist
  • Checks source files are present
  • Adds/updates version metadata
  • Reports any issues

Publish Documentation

Manually publish documentation to the docs repository:

./scripts/publish-docs.sh

This script provides two options:

  1. Trigger GitHub Actions (recommended) - Uses the automated workflow
  2. Manual Publication - Clones docs repo and creates PR locally

Setting Up GitHub Secrets

For the automation to work, you need to configure GitHub secrets:

Navigate to Repository Settings

Repository → Settings → Secrets and variables → Actions → New repository secret

Add Required Secrets

# For documentation publishing
DOCS_REPO_TOKEN=<github-personal-access-token>

Creating DOCS_REPO_TOKEN

  1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
  2. Create new token with:
    • Repository access: Only nevermined-io/docs_mintlify
    • Permissions:
      • Contents: Read and write
      • Pull requests: Read and write
  3. Copy token and add as DOCS_REPO_TOKEN secret

Release Process

Standard Release (Automated)

# 1. Update version in package.json
npm version patch  # or minor, major

# 2. Commit and push
git add package.json
git commit -m "chore: release v1.0.2"
git push origin main

# 3. Create and push tag (triggers publication)
git tag -a v1.0.2 -m "Release v1.0.2"
git push origin v1.0.2

# 4. GitHub Actions will:
#    - Update docs metadata (update-docs workflow)
#    - Publish to docs_mintlify (publish-docs workflow)
#    - Create PR in docs repository

# 5. Review and merge the PR in docs_mintlify

Manual Release (No Tag)

If you want to publish documentation without creating a tag:

# Option 1: Trigger workflow manually (to main branch)
gh workflow run publish-docs.yml -f version=v1.0.2

# Option 2: Trigger workflow to test/preview branch (for testing)
gh workflow run publish-docs.yml -f version=v1.0.2 -f target_branch=preview

# Option 3: Use publish script
./scripts/publish-docs.sh
# Select option 1 or 2

Testing Documentation Before Production

To preview documentation in Mintlify before publishing to production:

# 1. Create a preview branch in docs_mintlify (if it doesn't exist)
cd ../docs_mintlify
git checkout -b preview
git push origin preview

# 2. Publish documentation to preview branch
cd ../payments
gh workflow run publish-docs.yml -f version=v1.0.2 -f target_branch=preview

# 3. Review PR in docs_mintlify targeting preview branch

# 4. Merge PR and check Mintlify preview deployment

# 5. If satisfied, publish to main branch
gh workflow run publish-docs.yml -f version=v1.0.2 -f target_branch=main

Full Documentation Regeneration

When you need to completely regenerate the documentation (rare):

  1. Review Specification

    cat MINTLIFY_API_REFERENCE.md

  2. Use Claude Code

    Ask Claude Code:
"Regenerate all markdown documentation following the specification
in MINTLIFY_API_REFERENCE.md. Use tested code examples from the
tests/ directory."

  3. Validate Changes

    ./scripts/generate-docs.sh
git diff markdown/

  4. Commit Changes

    git add markdown/
git commit -m "docs: regenerate markdown documentation"
git push

Troubleshooting

Documentation Not Updated After Push

Problem: Pushed code changes but docs weren't updated

Check:

# View recent workflow runs
gh run list --workflow=update-docs.yml

# View specific run logs
gh run view <run-id> --log

Common Causes:

  • Commit message contains [skip ci]
  • Changes not in watched paths (src/, tests/, etc.)
  • Workflow file has syntax errors

Documentation Publishing Failed

Problem: Tagged release but PR wasn't created in docs repository

Check:

# View publish workflow runs
gh run list --workflow=publish-docs.yml

# View specific run logs
gh run view <run-id> --log

Common Causes:

  • DOCS_REPO_TOKEN is invalid or expired
  • Documentation files are missing or invalid
  • Target repository structure changed
  • Network issues during checkout

Solution:

# Validate docs locally
./scripts/generate-docs.sh

# Re-trigger workflow
gh workflow run publish-docs.yml -f version=v1.0.2

# Or publish manually
./scripts/publish-docs.sh

Pull Request Not Created

Problem: Workflow succeeded but no PR in docs repository

Check:

  1. DOCS_REPO_TOKEN has PR creation permissions
  2. No existing PR for the same branch exists
  3. No merge conflicts in target repository

Solution:

# Check PRs in docs repository
gh pr list --repo nevermined-io/docs_mintlify

# If branch exists but no PR, create manually
cd ../docs_mintlify
gh pr create --title "docs: Update TypeScript SDK Documentation (v1.0.2)"

Version Metadata Incorrect

Problem: Documentation shows wrong version number

Solution:

# Update version in package.json
npm version <new-version>

# Run validation script
./scripts/generate-docs.sh

# Commit changes
git add package.json markdown/
git commit -m "chore: update version to <new-version>"
git push

Documentation Guidelines

When to Update Documentation

Update documentation when:

  • ✅ Adding new API methods or classes
  • ✅ Changing method signatures
  • ✅ Adding new integration patterns (MCP, A2A, etc.)
  • ✅ Updating examples in tests
  • ✅ Fixing bugs that affect API usage
  • ✅ Major version releases

Don't update for:

  • ❌ Internal refactoring (no API changes)
  • ❌ Test-only changes
  • ❌ Documentation typo fixes (edit markdown directly)

Documentation Quality Standards

All documentation must:

  • ✅ Use TypeScript code examples
  • ✅ Source examples from working tests
  • ✅ Include clear, simple explanations
  • ✅ Follow consistent formatting
  • ✅ Link to related documentation
  • ✅ Include source references

Code Example Requirements

Every code example should:

  • Be complete and runnable
  • Use environment variables for sensitive data
  • Include necessary imports
  • Show expected output or next steps
  • Follow the project's coding style

Monitoring Workflows

GitHub Actions Dashboard

View all workflow runs:

Repository → Actions tab

Via GitHub CLI

# List recent runs
gh run list

# View specific workflow
gh run list --workflow=update-docs.yml
gh run list --workflow=publish-docs.yml

# View logs for a run
gh run view <run-id> --log

# Watch a running workflow
gh run watch <run-id>

Notifications

Configure GitHub notifications for workflow failures:

Settings → Notifications → Actions → Enable workflow notifications

FAQ

Q: How often does documentation update?

A: Automatically on every push to main/develop that changes source files. The workflow typically runs in 2-3 minutes.

Q: Can I publish docs without tagging?

A: Yes, use the manual trigger:

gh workflow run publish-docs.yml -f version=v1.0.2

Q: What if I need to unpublish documentation?

A: Close the PR in the docs repository or revert the merge commit. Documentation updates are not automatically deleted.

Q: How do I test workflow changes?

A: Use act to run workflows locally:

brew install act
act push -W .github/workflows/update-docs.yml

Q: Can I customize the PR template?

A: Yes, edit the body section in .github/workflows/publish-docs.yml under the "Create Pull Request" step.

Q: What happens if two releases are published simultaneously?

A: Each release creates a separate branch and PR. Both can coexist and be merged independently.

Resources