adjust docs UI

Author: anhnh2002

HTMLGENERATOR_IMPROVEMENTS.md

@@ -0,0 +1,311 @@
+# HTMLGenerator and Template Improvements
+
+## Summary
+
+Updated the HTMLGenerator class and its associated templates based on the frontend code and generated documentation examples. The improvements enable automatic loading of module trees and metadata, better navigation rendering, and enhanced user experience.
+
+## Changes Made
+
+### 1. HTMLGenerator Class (`codewiki/cli/html_generator.py`)
+
+#### New Methods
+
+**`load_module_tree(docs_dir: Path)`**
+- Automatically loads `module_tree.json` from the documentation directory
+- Provides fallback structure if file doesn't exist
+- Returns properly structured module tree for navigation rendering
+
+**`load_metadata(docs_dir: Path)`**
+- Loads `metadata.json` from the documentation directory
+- Returns None if not found (non-critical)
+- Enables display of generation information in the viewer
+
+#### Updated `generate()` Method
+
+**New Parameters:**
+- `docs_dir`: Documentation directory path for auto-loading
+- `metadata`: Metadata dictionary (auto-loaded if docs_dir provided)
+- `module_tree`: Now optional, auto-loaded from docs_dir if not provided
+
+**Key Improvements:**
+- Auto-loads module_tree.json and metadata.json when docs_dir is provided
+- Embeds metadata in the configuration for client-side display
+- Maintains backward compatibility with existing code
+
+**Before:**
+```python
+html_generator.generate(
+    output_path=output_path,
+    title=title,
+    module_tree=manual_module_tree,  # Had to be manually provided
+    repository_url=url
+)
+```
+
+**After:**
+```python
+html_generator.generate(
+    output_path=output_path,
+    title=title,
+    docs_dir=output_dir,  # Auto-loads module_tree and metadata
+    repository_url=url
+)
+```
+
+### 2. Documentation Generator Adapter (`codewiki/cli/adapters/doc_generator.py`)
+
+#### Updated `_run_html_generation()` Method
+
+**Before:**
+- Created placeholder module tree with just "Overview"
+- Ignored the actual generated module structure
+- No metadata integration
+
+**After:**
+- Uses `docs_dir` parameter for automatic loading
+- Properly loads the module_tree.json generated in stage 2
+- Automatically loads metadata.json for display
+- Adds progress update for loading phase
+
+### 3. JavaScript Application (`codewiki/templates/github_pages/app.js`)
+
+#### Enhanced Navigation Rendering
+
+**`renderNavTree()` Function:**
+- Improved recursive rendering for deeply nested structures
+- Skips metadata properties ('description', 'components') in iteration
+- Better handling of module data objects
+- Properly renders children at any depth level
+
+**New `formatModuleName()` Function:**
+- Converts underscores and hyphens to spaces
+- Capitalizes each word for better readability
+- Example: `search_providers` → `Search Providers`
+
+**New `renderMetadata()` Function:**
+- Creates styled metadata info box for sidebar
+- Displays generation information:
+  - Model used for generation
+  - Timestamp (formatted as locale string)
+  - Commit ID (first 8 characters)
+  - Total components count
+- Returns null if no metadata available
+
+#### Updated `init()` Function
+
+**Additions:**
+- Renders metadata info box in sidebar after overview link
+- Positioned between overview and divider for prominence
+- Only displays if metadata is available in config
+
+### 4. Styles (`codewiki/templates/github_pages/styles.css`)
+
+#### Navigation Improvements
+
+**Font Sizing for Nested Levels:**
+- Base level: 0.875rem
+- Second level (2rem padding): 0.8125rem, subdued color
+- Third level (3rem padding): 0.75rem, more subdued color
+- Improves visual hierarchy for deep structures
+
+**New Metadata Box Styling:**
+- Dedicated `.metadata-box` class
+- Consistent styling with theme
+- Proper spacing and borders
+
+#### Content Enhancements
+
+**Blockquote Styling:**
+- Blue left border (matches theme)
+- Light background
+- Proper padding and margins
+
+**Image Handling:**
+- `max-width: 100%` for responsiveness
+- Auto height to maintain aspect ratio
+- Rounded corners (6px)
+- Proper margins
+
+**Horizontal Rules:**
+- Clean, minimal styling
+- Consistent with theme colors
+- Generous vertical spacing
+
+**Mermaid Diagrams:**
+- White background for contrast
+- Light border and rounded corners
+- Center alignment
+- Proper padding and margins
+
+**Loading State:**
+- Center-aligned loading indicator
+- Subdued color scheme
+- Adequate padding
+
+#### Layout Improvements
+
+**Footer Support:**
+- `#app` uses `min-height` instead of `height` for proper scrolling
+- `#footer` uses `margin-top: auto` to stick to bottom
+- Proper flex layout for sticky footer
+
+### 5. HTML Template (`codewiki/templates/github_pages/index.html`)
+
+#### New Footer Section
+
+**Added:**
+- Footer with CodeWiki attribution
+- Positioned at bottom of page
+- Subtle styling with theme colors
+- Link to project (placeholder for actual URL)
+
+**Benefits:**
+- Professional appearance
+- Clear attribution
+- Consistent with modern web practices
+
+## Benefits of These Improvements
+
+### 1. Automated Data Loading
+- No need to manually load module_tree.json
+- Metadata automatically integrated
+- Reduces code duplication
+- Fewer errors from manual data handling
+
+### 2. Better Navigation
+- Proper rendering of nested module structures
+- Clear visual hierarchy
+- Better readability with formatted names
+- Supports arbitrary nesting depth
+
+### 3. Enhanced User Experience
+- Generation information visible in sidebar
+- Model, timestamp, commit info at a glance
+- Better understanding of documentation provenance
+- Professional appearance with footer
+
+### 4. Improved Styling
+- Better support for nested navigation
+- Enhanced markdown rendering
+- Responsive images
+- Proper mermaid diagram display
+- Sticky footer layout
+
+### 5. Code Quality
+- Better separation of concerns
+- More reusable components
+- Improved error handling
+- Backward compatible
+
+## Testing Recommendations
+
+1. **Test with Real Repository:**
+   ```bash
+   cd /path/to/test-repo
+   codewiki generate --github-pages
+   ```
+
+2. **Verify Module Tree Rendering:**
+   - Check that all nested modules appear
+   - Verify indentation and hierarchy
+   - Test navigation clicks
+
+3. **Check Metadata Display:**
+   - Verify generation info box appears
+   - Check model name display
+   - Verify timestamp formatting
+   - Test with and without commit ID
+
+4. **Test Responsive Design:**
+   - View on mobile devices
+   - Test sidebar toggle
+   - Verify navigation usability
+   - Check content readability
+
+5. **Verify Markdown Rendering:**
+   - Test code blocks with syntax highlighting
+   - Verify mermaid diagram rendering
+   - Check image display
+   - Test blockquotes and lists
+
+## Migration Guide
+
+### For Existing Code
+
+**Old usage:**
+```python
+html_generator = HTMLGenerator()
+module_tree = load_some_module_tree()
+html_generator.generate(
+    output_path=output_path,
+    title=title,
+    module_tree=module_tree
+)
+```
+
+**New usage (recommended):**
+```python
+html_generator = HTMLGenerator()
+html_generator.generate(
+    output_path=output_path,
+    title=title,
+    docs_dir=docs_directory  # Auto-loads everything
+)
+```
+
+**Still supported (backward compatible):**
+```python
+html_generator = HTMLGenerator()
+html_generator.generate(
+    output_path=output_path,
+    title=title,
+    module_tree=manually_loaded_tree  # Still works
+)
+```
+
+## Future Enhancements
+
+Potential improvements for future iterations:
+
+1. **Search Functionality:**
+   - Full-text search across documentation
+   - Module/component search
+   - Code snippet search
+
+2. **Dark Mode:**
+   - Theme toggle
+   - System preference detection
+   - Persistent user preference
+
+3. **Table of Contents:**
+   - Auto-generated from headers
+   - Sticky sidebar TOC
+   - Smooth scrolling
+
+4. **Dependency Graphs:**
+   - Interactive visualization
+   - Load from temp/dependency_graphs
+   - Zoom and pan support
+
+5. **Code Copy Button:**
+   - One-click code copying
+   - Visual feedback
+   - Syntax-aware copying
+
+6. **Version Selector:**
+   - Multiple doc versions
+   - Comparison view
+   - Changelog integration
+
+## Files Modified
+
+1. `/Users/anhnh/Documents/vscode/CodeWiki/codewiki/cli/html_generator.py`
+2. `/Users/anhnh/Documents/vscode/CodeWiki/codewiki/cli/adapters/doc_generator.py`
+3. `/Users/anhnh/Documents/vscode/CodeWiki/codewiki/templates/github_pages/app.js`
+4. `/Users/anhnh/Documents/vscode/CodeWiki/codewiki/templates/github_pages/styles.css`
+5. `/Users/anhnh/Documents/vscode/CodeWiki/codewiki/templates/github_pages/index.html`
+
+## Conclusion
+
+These improvements bring the CLI's HTMLGenerator in line with the frontend implementation while maintaining backward compatibility and adding new features. The auto-loading functionality significantly simplifies usage, while the enhanced navigation and metadata display provide a better user experience.
+