From ce5b5c20bb6cd3f2d2101d7d71e8e1a07bd76576 Mon Sep 17 00:00:00 2001 From: Kaj Kowalski Date: Wed, 28 May 2025 13:17:08 +0200 Subject: [PATCH] Enhances README and script improvements Updates README to include HTML format, architecture overview, and comprehensive feature descriptions. Improves build scripts by adding cleanup of environment variables and validating Go installation, reducing cross-platform build issues. Fixes README inconsistencies and improves script reliability. --- README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++-- scripts/build.ps1 | 5 +++ scripts/build.sh | 13 ++++++- 3 files changed, 109 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 7a0d751..9126e95 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,78 @@ # Articulate Rise Parser -A Go-based parser that converts Articulate Rise e-learning content to various formats including Markdown and Word documents. +A Go-based parser that converts Articulate Rise e-learning content to various formats including Markdown, HTML, and Word documents. + +## System Architecture + +```mermaid +flowchart TD + %% User Input + CLI[Command Line Interface
main.go] --> APP{App Service
services/app.go} + + %% Core Application Logic + APP --> |"ProcessCourseFromURI"| PARSER[Course Parser
services/parser.go] + APP --> |"ProcessCourseFromFile"| PARSER + APP --> |"exportCourse"| FACTORY[Exporter Factory
exporters/factory.go] + + %% Data Sources + PARSER --> |"FetchCourse"| API[Articulate Rise API
rise.articulate.com] + PARSER --> |"LoadCourseFromFile"| FILE[Local JSON File
*.json] + + %% Data Models + API --> MODELS[Data Models
models/course.go] + FILE --> MODELS + MODELS --> |Course, Lesson, Item| APP + + %% Export Factory Pattern + FACTORY --> |"CreateExporter"| MARKDOWN[Markdown Exporter
exporters/markdown.go] + FACTORY --> |"CreateExporter"| HTML[HTML Exporter
exporters/html.go] + FACTORY --> |"CreateExporter"| DOCX[DOCX Exporter
exporters/docx.go] + + %% HTML Cleaning Service + CLEANER[HTML Cleaner
services/html_cleaner.go] --> MARKDOWN + CLEANER --> HTML + CLEANER --> DOCX + + %% Output Files + MARKDOWN --> |"Export"| MD_OUT[Markdown Files
*.md] + HTML --> |"Export"| HTML_OUT[HTML Files
*.html] + DOCX --> |"Export"| DOCX_OUT[Word Documents
*.docx] + + %% Interfaces (Contracts) + IPARSER[CourseParser Interface
interfaces/parser.go] -.-> PARSER + IEXPORTER[Exporter Interface
interfaces/exporter.go] -.-> MARKDOWN + IEXPORTER -.-> HTML + IEXPORTER -.-> DOCX + IFACTORY[ExporterFactory Interface
interfaces/exporter.go] -.-> FACTORY + + %% Styling + classDef userInput fill:#e1f5fe,stroke:#01579b,stroke-width:2px + classDef coreLogic fill:#f3e5f5,stroke:#4a148c,stroke-width:2px + classDef dataSource fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px + classDef exporter fill:#fff3e0,stroke:#e65100,stroke-width:2px + classDef output fill:#fce4ec,stroke:#880e4f,stroke-width:2px + classDef interface fill:#f1f8e9,stroke:#33691e,stroke-width:1px,stroke-dasharray: 5 5 + classDef service fill:#e0f2f1,stroke:#00695c,stroke-width:2px + + class CLI userInput + class APP,FACTORY coreLogic + class API,FILE,MODELS dataSource + class MARKDOWN,HTML,DOCX exporter + class MD_OUT,HTML_OUT,DOCX_OUT output + class IPARSER,IEXPORTER,IFACTORY interface + class PARSER,CLEANER service +``` + +### Architecture Overview + +The system follows **Clean Architecture** principles with clear separation of concerns: + +- **🎯 Entry Point**: Command-line interface handles user input and coordinates operations +- **🏗️ Application Layer**: Core business logic with dependency injection +- **📋 Interface Layer**: Contracts defining behavior without implementation details +- **🔧 Service Layer**: Concrete implementations of parsing and utility services +- **📤 Export Layer**: Factory pattern for format-specific exporters +- **📊 Data Layer**: Domain models representing course structure [![Go version](https://img.shields.io/github/go-mod/go-version/kjanat/articulate-parser?logo=Go&logoColor=white)][gomod] [![Go Doc](https://godoc.org/github.com/kjanat/articulate-parser?status.svg)][Package documentation] @@ -16,6 +88,7 @@ A Go-based parser that converts Articulate Rise e-learning content to various fo - Parse Articulate Rise JSON data from URLs or local files - Export to Markdown (.md) format +- Export to HTML (.html) format with professional styling - Export to Word Document (.docx) format - Support for various content types: - Text content with headings and paragraphs @@ -85,7 +158,7 @@ go run main.go [output_path] | Parameter | Description | Default | | ------------------- | ---------------------------------------------------------------- | --------------- | | `input_uri_or_file` | Either an Articulate Rise share URL or path to a local JSON file | None (required) | -| `output_format` | `md` for Markdown or `docx` for Word Document | None (required) | +| `output_format` | `md` for Markdown, `html` for HTML, or `docx` for Word Document | None (required) | | `output_path` | Path where output file will be saved. | `./output/` | #### Examples @@ -102,7 +175,13 @@ go run main.go "https://rise.articulate.com/share/N_APNg40Vr2CSH2xNz-ZLATM5kNviD go run main.go "articulate-sample.json" docx "my-course.docx" ``` -3. **Parse from local file and export to Markdown:** +3. **Parse from local file and export to HTML:** + +```bash +go run main.go "articulate-sample.json" html "output.html" +``` + +4. **Parse from local file and export to Markdown:** ```bash go run main.go "articulate-sample.json" md "output.md" @@ -153,6 +232,15 @@ The project maintains high code quality standards: - Media references included - Course metadata at the top +### HTML (`.html`) + +- Professional styling with embedded CSS +- Interactive and visually appealing layout +- Proper HTML structure with semantic elements +- Responsive design for different screen sizes +- All content types beautifully formatted +- Maintains course hierarchy and organization + ### Word Document (`.docx`) - Professional document formatting @@ -230,7 +318,7 @@ Potential improvements could include: - PDF export support - Media file downloading -- HTML export with preserved styling +- ~~HTML export with preserved styling~~ ✅ **Completed** - SCORM package support - Batch processing capabilities - Custom template support diff --git a/scripts/build.ps1 b/scripts/build.ps1 index 08302a2..eb3ce1d 100644 --- a/scripts/build.ps1 +++ b/scripts/build.ps1 @@ -531,6 +531,11 @@ try { if ($Failed -gt 0) { exit 1 } + + # Clean up environment variables to avoid contaminating future builds + Remove-Item Env:GOOS -ErrorAction SilentlyContinue + Remove-Item Env:GOARCH -ErrorAction SilentlyContinue + Remove-Item Env:CGO_ENABLED -ErrorAction SilentlyContinue } finally { Pop-Location } diff --git a/scripts/build.sh b/scripts/build.sh index 3f79521..d0739ad 100644 --- a/scripts/build.sh +++ b/scripts/build.sh @@ -217,6 +217,14 @@ if [ "$SHOW_TARGETS" = true ]; then exit 0 fi +# Validate Go installation +if ! command -v go >/dev/null 2>&1; then + echo "Error: Go is not installed or not in PATH" + echo "Please install Go from https://golang.org/dl/" + echo "Or if running on Windows, use the PowerShell script: scripts\\build.ps1" + exit 1 +fi + # Validate entry point exists if [ ! -f "$ENTRYPOINT" ]; then echo "Error: Entry point file '$ENTRYPOINT' does not exist" @@ -315,7 +323,7 @@ for idx in "${!TARGETS[@]}"; do fi build_cmd+=("${GO_BUILD_FLAGS_ARRAY[@]}" -o "$OUTDIR/$BIN" "$ENTRYPOINT") - if CGO_ENABLED=1 GOOS="$os" GOARCH="$arch" "${build_cmd[@]}" 2>"$OUTDIR/$BIN.log"; then + if CGO_ENABLED=0 GOOS="$os" GOARCH="$arch" "${build_cmd[@]}" 2>"$OUTDIR/$BIN.log"; then update_status $((idx + 1)) '✔' "$BIN done" rm -f "$OUTDIR/$BIN.log" else @@ -356,3 +364,6 @@ if [ "$VERBOSE" = true ]; then echo " ────────────────────────────────────────────────" printf " Total: %d/%d successful, %s total size\n" "$success_count" "${#TARGETS[@]}" "$(numfmt --to=iec-i --suffix=B $total_size 2>/dev/null || echo "${total_size} bytes")" fi + +# Clean up environment variables to avoid contaminating future builds +unset GOOS GOARCH CGO_ENABLED