OS Migrate Documentation

This is the documentation repository for OS Migrate, an open source toolbox for parallel OpenStack cloud migration. The repository contains AsciiDoc-formatted documentation.

Structure

• index.adoc - Main documentation entry point
• operator/ - Operator documentation (guides, VMware migration, troubleshooting)
• developer/ - Developer documentation (contributing, design, development setup)
• reference/ - Reference documentation
  • modules/ - Ansible module documentation
  • roles/ - Ansible role documentation
• images/ - Static SVG workflow diagrams

Building Documentation

Prerequisites

Install Ruby dependencies using bundler:

bundle install

Build Commands

# Build HTML documentation
make html

# or simply
make

# Clean build artifacts
make clean

# Show available build targets
make help

Output

Built documentation will be available at:

• HTML: docs/index.html
• Images: docs/images/ (SVG files automatically copied during build)

Features

• AsciiDoc format: Human-readable documentation source format
• SVG workflow diagrams: Static diagrams for VMware migration workflows
• Table of contents: Left sidebar navigation (3 levels deep)
• Syntax highlighting: Code block highlighting with Rouge
• Modular structure: Include directives for organizing content
• Cross-references: Automatic section linking and anchors

Ruby Dependencies

The project uses these Ruby gems (defined in Gemfile):

• asciidoctor (~> 2.0) - Core AsciiDoc processor
• rouge (~> 4.1) - Syntax highlighting