Automated Documentation Deployment

Purpose and Scope

This document describes the automated CI/CD pipeline that generates API documentation from source code and deploys it to GitHub Pages. The system uses GitHub Actions to execute the JSDoc documentation generator and publish versioned documentation on every push to the main branch.

For information about JSDoc configuration and documentation generation settings, see JSDoc Configuration. For the overall documentation system architecture, see Documentation System.

Overview

The automated documentation deployment system consists of a GitHub Actions workflow that:

1. Triggers on pushes to the main branch
2. Extracts the current package version from package.json
3. Generates HTML documentation using JSDoc
4. Deploys the versioned documentation to GitHub Pages

The generated documentation is version-specific and published to https://codeblech.github.io/jsjiit/docs/jsjiit/{version}/, where {version} corresponds to the version defined in package.json.

Sources: .github/workflows/jsdoc-build.yaml1-27 package.json2-3

Automation Pipeline Architecture

The following diagram illustrates the complete automated documentation deployment pipeline:

Sources: .github/workflows/jsdoc-build.yaml1-27

Workflow Configuration

The automation is defined in .github/workflows/jsdoc-build.yaml and configured to run on specific events and with specific permissions.

Trigger Configuration

The workflow is triggered on pushes to the main branch:

.github/workflows/jsdoc-build.yaml1-4

This ensures documentation is rebuilt and deployed whenever changes are merged to the main branch.

Permissions

The workflow requires write permissions to the repository contents to deploy to GitHub Pages:

.github/workflows/jsdoc-build.yaml8-9

Runtime Environment

The workflow runs on the latest Ubuntu runner provided by GitHub Actions:

.github/workflows/jsdoc-build.yaml10

Sources: .github/workflows/jsdoc-build.yaml1-10

Build Process Steps

The build job consists of four sequential steps that checkout code, extract version information, generate documentation, and deploy to GitHub Pages.

Step 1: Repository Checkout

The first step clones the repository to the GitHub Actions runner:

.github/workflows/jsdoc-build.yaml12-13

This uses the actions/checkout@v2 action to retrieve the full repository contents.

Step 2: Version Extraction

The workflow extracts the current package version from package.json using Node.js:

.github/workflows/jsdoc-build.yaml14-16

The version is extracted by executing node -p "require('./package.json').version" and storing it in the GITHUB_OUTPUT environment file. This allows subsequent steps to reference the version via ${{ steps.get_version.outputs.version }}.

Step 3: Documentation Generation

The JSDoc documentation is generated using the andstor/jsdoc-action@v1 action:

.github/workflows/jsdoc-build.yaml17-21

The action uses the JSDoc configuration file at jsdoc.conf.json1-25 and processes source files recursively. The generated documentation is output to ./docs/ as specified in the JSDoc configuration.

Step 4: GitHub Pages Deployment

The final step deploys the generated documentation to GitHub Pages:

.github/workflows/jsdoc-build.yaml22-26

The peaceiris/actions-gh-pages@v3 action publishes the versioned documentation directory (./docs/jsjiit/{version}) to the gh-pages branch using the GITHUB_TOKEN secret for authentication.

Sources: .github/workflows/jsdoc-build.yaml12-26

Deployment Mechanism

The following diagram shows how the deployment action interacts with GitHub's infrastructure:

Sources: .github/workflows/jsdoc-build.yaml1-27 package.json3 jsdoc.conf.json14-16

Versioned Documentation Structure

The deployment creates a versioned documentation structure that allows multiple versions of the documentation to coexist.

Version-Specific Publishing

The publish directory is dynamically constructed using the extracted version:

.github/workflows/jsdoc-build.yaml26

This results in documentation being published to a version-specific path. For example, if package.json defines version 0.0.23, the documentation is published to:

./docs/jsjiit/0.0.23/

Documentation URL Pattern

The resulting GitHub Pages URL follows the pattern:

https://codeblech.github.io/jsjiit/docs/jsjiit/{version}/index.html

Where {version} is replaced with the actual version number from package.json.

Benefits of Versioned Documentation

Sources: .github/workflows/jsdoc-build.yaml26 package.json3

Integration with Package Management

The documentation deployment is integrated with the package publishing workflow through version synchronization.

Version Source of Truth

The package.json serves as the single source of truth for version information:

package.json3

This version is used by:

• npm package publishing
• Documentation deployment path
• JSDoc metadata generation

Documentation Script

While the automated deployment uses GitHub Actions, developers can generate documentation locally using the npm script:

package.json14

This script runs JSDoc with the same configuration file used by the GitHub Actions workflow, ensuring consistency between local and deployed documentation.

Git Ignore Configuration

The locally generated documentation directory is excluded from version control:

.gitignore2

This prevents committing generated documentation to the repository, as it is automatically generated and deployed by GitHub Actions.

Sources: package.json3-14 .gitignore2

Workflow Execution Flow

The following diagram maps the workflow steps to specific code entities and configuration files:

Sources: .github/workflows/jsdoc-build.yaml1-27 jsdoc.conf.json1-25

Error Handling and Permissions

The workflow includes several mechanisms to ensure reliable documentation deployment.

Required Permissions

The workflow explicitly requests contents: write permission:

.github/workflows/jsdoc-build.yaml8-9

This permission is required for the peaceiris/actions-gh-pages@v3 action to push to the gh-pages branch.

Authentication

The deployment step uses the built-in GITHUB_TOKEN secret:

.github/workflows/jsdoc-build.yaml25

This token is automatically provided by GitHub Actions and has the necessary permissions to deploy to GitHub Pages when contents: write is specified.

Workflow Failures

If any step fails, the workflow stops execution and reports the failure. Common failure scenarios include:

Sources: .github/workflows/jsdoc-build.yaml8-25

Summary

The automated documentation deployment system provides a fully automated pipeline that:

1. Triggers automatically on pushes to the main branch
2. Extracts version dynamically from package.json
3. Generates documentation using JSDoc with the configuration defined in jsdoc.conf.json
4. Deploys to GitHub Pages in a version-specific directory structure
5. Requires no manual intervention after initial setup

This automation ensures documentation remains synchronized with the codebase, provides version-specific documentation URLs, and eliminates manual deployment tasks.

Sources: .github/workflows/jsdoc-build.yaml1-27 package.json3-14 jsdoc.conf.json1-25 .gitignore2