Unified Build System Documentation Update Plan (Task 17.8)

Overview

This document logs the implementation plan for subtask 17.8: Update and Publish Documentation for the Codexis Unified Build System with Shared Temporary Directory.

1. Documentation Targets

a. User-Facing Documentation

• docs-site/docs/unified-build-system-guide.md
  (Main user guide for the new build system)
• docs-site/docs/unified-build-system-troubleshooting.md
  (Troubleshooting and FAQ)
• docs-site/docs/architecture/decisions/0034-unified-build-system.md
  (ADR for architecture and migration)
• CLAUDE.md
  (Quick reference for contributors and LLMs)

b. Module and API Documentation

• lib/codexis/build_manager/build_orchestrator.ex
  (Module doc: orchestrator API, directory structure, usage)
• lib/codexis/core/file_manager.ex
  (Module doc: file operations, security, migration from File)
• lib/codexis/commands/build_command.ex
  (CLI help text, flag documentation, usage examples)
• lib/codexis/commands/build_dir_status_command.ex
  (CLI command for temp dir status/troubleshooting)

c. Migration and Developer Docs

• docs/file_operations_migration.md
  (Migration guide for file/path handling)
• docs/testing/unified_build_system_testing.md
  (Testing strategy and coverage for the new system)

2. Documentation Update Plan

a. User Guide

• Cover new directory structure (with diagrams)
• CLI usage and new flags (--show-temp-status, --cleanup-temp, etc.)
• Debugging and troubleshooting workflows
• Migration notes for users of the old system

b. Troubleshooting

• Expand on common errors (permissions, disk space, LaTeX failures)
• How to use CLI flags for diagnosis and cleanup
• Recovery procedures and best practices for CI, Docker, NFS

c. ADR and Migration

• Confirm ADR 0034 is up to date with rationale, benefits, migration path, and compatibility

d. Module Docs

• Ensure all public modules/functions have @moduledoc and @doc with usage examples
• Explain new APIs and migration from legacy patterns

e. CLI Help and Examples

• Verify CLI help text references new features
• Add usage examples for new flags and troubleshooting commands

f. Migration Guide

• Document how to update scripts/code to use the new system
• Migrate from direct File operations to FileManager/PathBuilder
• Security and performance rationale

g. Testing Docs

• Summarize new testing strategy and how to run/extend tests for the unified system

3. Execution Steps

1. Review and update each documentation file as outlined above.
2. Add/expand code examples and diagrams where helpful.
3. Ensure all CLI help and module docs are consistent and reference the unified system.
4. Update migration and troubleshooting guides with real-world scenarios and solutions.
5. Publish and verify documentation builds (if applicable).

4. Next Steps

• Log this plan in the subtask and begin the documentation update process.
• Prioritize user-facing documentation and migration guides, then update module docs and CLI help.
• Coordinate with testing and development teams to ensure documentation accuracy.