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 that assembles both guides and the common reference
• source/ - All AsciiDoc documentation files
  • vmware/ - VMware to OpenStack guide (modular con_/proc_/ref_ topics and its assembly)
  • os-to-os/ - OpenStack to OpenStack guide (modular topics and its assembly)
  • shared/ - Blocks included by both guides (migrator host, conversion hosts, installation, glossary)
  • developer-*.adoc - Developer documentation (contributing, design, development setup)
  • reference-module-*.adoc - Ansible module reference documentation
  • reference-role-*.adoc - Ansible role reference documentation
• images/ - Static workflow diagrams
• build/ - Build output directory (generated)

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: build/index.html
• Images: build/images/ (SVG files automatically copied during build)

Features

• AsciiDoc format: Human-readable documentation source format
• Single-page HTML: All documentation built into one HTML file
• 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

Build Configuration

The Makefile uses AsciiDoctor with the following configuration:

• toc=left - Table of contents on left sidebar
• toclevels=3 - Show 3 levels in TOC
• sectlinks - Make section titles clickable links
• sectanchors - Add anchor symbols to sections
• source-highlighter=rouge - Syntax highlighting with Rouge

Ruby Dependencies

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

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

The upstream documentation is available at the OS Migrate documentation repository.