Nimbus Documentation Build System

This is a TypeScript-based documentation build system for the Nimbus project. It handles building, updating, and synchronizing documentation with the API.

Features

• Document changes detection based on content hashing
• API synchronization with CRUD operations
• MDX file parsing and processing for documentation
• Component props fetching from GitHub repositories
• Dry-run mode for local development
• Git integration for branch comparison
• TypeScript-based with proper type definitions
• Parametrizable file paths via command line arguments

Structure

The system follows SOLID principles and is organized into several modules:

docs-build/
├── src/
│   ├── api/              - API interaction layer
│   ├── commands/         - Command implementations
│   ├── core/             - Core documentation processing
│   ├── hashing/          - Document hashing functionality
│   ├── services/         - External services like GitHub
│   ├── utils/            - Utility services like Git operations
│   ├── config.ts         - Configuration settings
│   ├── types.ts          - Type definitions
│   └── index.ts          - Main entry point
├── package.json
├── tsconfig.json
└── README.md

Getting Started

Prerequisites

• Node.js 14+ and Yarn
• Git

Installation

cd docs-build
yarn install

Build

yarn build

Usage

To generate a preview of document changes:

yarn build:docs preview

To update document hashes and sync with the API:

yarn build:docs update

To parse MDX files and generate documentation chunks:

yarn parse-mdx

To preview MDX parsing changes without updating files:

yarn parse-mdx:preview

Use the --force flag to override dry-run mode in local development:

yarn build:docs update --force

Custom File Paths

You can specify custom file paths for hash storage and document files:

yarn build:docs update --hashesFile=./custom-path/hashes.json --genDocumentsFile=./custom-path/documents.json

Using Mock Hashes for Comparison

For development or testing, you can use a mock hashes file instead of comparing with the master branch:

# First initialize the mock hashes file (only needed once)
yarn init:mock

# Then run with the mock hashes file
yarn build:docs update --hashMocks=.docs-build/hash-mocks.json

# Or use the convenience script
yarn build:docs:mock

This is especially useful before a file is merged into the master branch when you need to test change detection.

When using the mock hashes feature:

1. On first run, an empty mock hashes file will be created if it doesn't exist
2. Changes will be detected compared to the mock hashes file, not the master branch
3. The mock hashes file will be updated with the current hashes after processing

For MDX parsing with mock hashes:

yarn parse-mdx:mock

Environment Variables

The system uses the following environment variables:

• DOCS_API_ENDPOINT - The API endpoint for document operations
• DOCS_API_KEY - API authentication key (optional, if needed)
• GITHUB_TOKEN - GitHub token for API access (optional, but recommended)

GitHub Actions Integration

This system is designed to be run from GitHub Actions. In the GitHub environment, it will automatically detect it's running in CI/CD and switch to production mode.

Development

For local development, the system runs in dry-run mode by default, which prevents modifications to production files and API.

To force the system to make actual changes in development:

yarn build:docs update --force

License

Internal - Nimbus Project