Overview

Maintaining API documentation can be a repetitive task. Using apidoc, you can generate documentation directly from comments within your source code. This approach is non-intrusive and supports multiple languages including Java, Python, Go, PHP, and JavaScript. By integrating it with version control and a web server, you can ensure that your technical documentation stays synchronized with the codebase without manual intervention.

Environment Configuration

To set up an automated pipeline on a Linux system (such as CentOS), the following components are required:

Installing Dependencies

First, install the necessary packages and the apidoc global module.

# Install Git and Node.js environment
sudo yum install -y git nodejs npm

# Set NPM registry to a faster mirror if needed
npm config set registry https://registry.npmmirror.com

# Install apidoc globally
sudo npm install -g apidoc

# Verify installation
git --version
apidoc -v

Nginx Setup

Configure the Nginx repository to install the stable version.

cat <<EOF > /etc/yum.repos.d/nginx.repo
[nginx-stable]
name=nginx stable repo
baseurl=http://nginx.org/packages/centos/\$releasever/\$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true
EOF

sudo yum install -y nginx
sudo systemctl enable nginx
sudo systemctl start nginx

Document Generation Workflow

1. Repository Preparation

Clone the target repository containing the source code with apidoc formatted comments.

mkdir -p /data/docs && cd /data/docs
git clone https://github.com/example/api-project.git

2. Manual Build Script

You can use a simple script to pull the latest changes and trigger the documentation build.

#!/bin/bash
# build_docs.sh

TARGET_DIR="api-project"

if [ -d "$TARGET_DIR/.git" ]; then
    echo "Updating repository..."
    cd "$TARGET_DIR" && git pull && cd ..
fi

echo "Generating documentation..."
apidoc -i "$TARGET_DIR/src" -o "./html_output"

Web Publication

Configure Nginx to serve the directory where apidoc outputs the static HTML files. Edit your site configuration (e.g., /etc/nginx/conf.d/docs.conf):

server {
    listen       80;
    server_name  docs.example.com;

    location / {
        root   /data/docs/html_output;
        index  index.html index.htm;
    }
}

Reload Nginx to apply changes:

sudo nginx -t
sudo nginx -s reload

Automated Syncing via Cron

To avoid manual updates, use a scheduled task to check for code changes. If new commits are detected, the script rebuilds the documentation.

Optimized Sync Script

Create a script named auto_sync.sh that minimizes resource usage by checking timestamps:

#!/bin/bash

PROJECT_NAME="api-project"
ROOT_DIR=$(pwd)
REPO_PATH="$ROOT_DIR/$PROJECT_NAME"
TIMESTAMP_FILE="$ROOT_DIR/.last_build"

# Initialize timestamp if not exists
[ -f "$TIMESTAMP_FILE" ] || echo "0" > "$TIMESTAMP_FILE"

# Fetch updates
cd "$REPO_PATH" && git pull > /dev/null

# Get the unix timestamp of the latest commit
LATEST_UPDATE=$(git log -1 --format="%at")
PREVIOUS_UPDATE=$(cat "$TIMESTAMP_FILE")

if [ "$LATEST_UPDATE" -gt "$PREVIOUS_UPDATE" ]; then
    echo "New changes found. Rebuilding..."
    /usr/local/bin/apidoc -i "$REPO_PATH/src" -o "$ROOT_DIR/html_output"
    echo "$LATEST_UPDATE" > "$TIMESTAMP_FILE"
else
    echo "No changes detected."
fi

Scheduling the Task

Add the script to crontab to run every few minutes:

crontab -e

Add the following entry (ensure absolute path are used for system commands):

*/5 * * * * cd /data/docs && bash auto_sync.sh

Alternative: Docker Environment

If you prefer not to manage Node.js and dependencies on the host, you can use a Dockerized apidoc image. This encapsulates the anvironment and allows you to run the generation within a container, mounting your source code and output directories as volumes. This approach simplifies cross-platform deployment and environment consistency.

CI/CD Integration

For more robust workflows, consider integrating apidoc into a CI/CD pipeline like Jenkins or GitHub Actions. In this scenario, the build is triggered by a Webhook every time code is pushed to the repository, eliminating the need for polling with Cron and providing immediate updates to the documentation.