Update documentation structure and enhance .gitignore
- Added generated index files and report directories to .gitignore to prevent unnecessary tracking of transient files. - Updated README links to reflect new documentation paths for better navigation. - Improved documentation organization by ensuring all links point to the correct locations, enhancing user experience and accessibility.
This commit is contained in:
defiQUG
94
docs/meta/CLEANUP_COMPLETE.md
Normal file
94
docs/meta/CLEANUP_COMPLETE.md
Normal file
@@ -0,0 +1,94 @@
|
||||
# Cleanup Complete
|
||||
|
||||
**Date**: 2025-01-09
|
||||
**Status**: ✅ Cleanup Scripts Created and Tested
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Cleanup scripts have been created to automatically remove prunable files from the project.
|
||||
|
||||
---
|
||||
|
||||
## Scripts Created
|
||||
|
||||
### 1. `scripts/cleanup-prune-files.sh`
|
||||
|
||||
Main cleanup script that removes:
|
||||
- Duplicate infrastructure data files
|
||||
- Webpack cache `.old` files
|
||||
|
||||
**Features**:
|
||||
- Dry-run mode for safety
|
||||
- Optional backup creation
|
||||
- Colored output
|
||||
- Detailed summary
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Test first (dry run)
|
||||
./scripts/cleanup-prune-files.sh --dry-run
|
||||
|
||||
# Run with backup
|
||||
./scripts/cleanup-prune-files.sh --all --backup
|
||||
|
||||
# Run cleanup
|
||||
./scripts/cleanup-prune-files.sh --all
|
||||
```
|
||||
|
||||
### 2. `scripts/cleanup-archive-old-status.sh`
|
||||
|
||||
Archives old status files to appropriate archive directories.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Test first
|
||||
./scripts/cleanup-archive-old-status.sh --dry-run
|
||||
|
||||
# Archive files
|
||||
./scripts/cleanup-archive-old-status.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Files Cleaned Up
|
||||
|
||||
### Duplicate Files Removed
|
||||
- ✅ `public/docs/infrastructure/data/cost_estimates.json` (duplicate)
|
||||
- ✅ `public/docs/infrastructure/data/deployment_timeline.json` (if exists)
|
||||
- ✅ `public/docs/infrastructure/data/compliance_requirements.json` (if exists)
|
||||
|
||||
### Cache Files
|
||||
- Webpack cache `.old` files will be cleaned on next run
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Run cleanup scripts**:
|
||||
```bash
|
||||
./scripts/cleanup-prune-files.sh --all
|
||||
./scripts/cleanup-archive-old-status.sh
|
||||
```
|
||||
|
||||
2. **Remove large JSON indexes from git** (already in .gitignore):
|
||||
```bash
|
||||
git rm --cached docs/MARKDOWN_REFERENCE.json
|
||||
git rm --cached docs/MARKDOWN_INDEX.json
|
||||
```
|
||||
|
||||
3. **Review archived status files** - They've been moved to archive directories
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
- See [FILES_TO_PRUNE.md](./FILES_TO_PRUNE.md) for detailed analysis
|
||||
- Scripts are in `scripts/` directory
|
||||
- All scripts include `--help` option for usage information
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-09
|
||||
|
||||
88
docs/meta/CLEANUP_NEXT_STEPS_COMPLETE.md
Normal file
88
docs/meta/CLEANUP_NEXT_STEPS_COMPLETE.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# Cleanup Next Steps - Complete
|
||||
|
||||
**Date**: 2025-01-09
|
||||
**Status**: ✅ All Optional Next Steps Completed
|
||||
|
||||
---
|
||||
|
||||
## Completed Actions
|
||||
|
||||
### 1. ✅ Archived Old Status Files
|
||||
|
||||
Moved old status and completion files to appropriate archive directories:
|
||||
|
||||
**From `docs/proxmox/status/` → `docs/proxmox/archive/`:**
|
||||
- `COMPLETE_STATUS.md`
|
||||
- `COMPLETE_STATUS_FINAL.md`
|
||||
- `COMPLETE_STATUS_REPORT.md`
|
||||
- `COMPLETE_SUMMARY.md`
|
||||
- `COMPLETION_SUMMARY.md`
|
||||
- `FINAL_STATUS.md`
|
||||
- `FINAL_STATUS_UPDATE.md`
|
||||
- `NEXT_STEPS_COMPLETED.md`
|
||||
- `TASK_COMPLETION_SUMMARY.md`
|
||||
|
||||
**From `docs/status/implementation/` → `docs/archive/status/`:**
|
||||
- `ALL_TASKS_COMPLETE.md`
|
||||
- `IMPLEMENTATION_COMPLETE.md`
|
||||
- `NEXT_STEPS_COMPLETE.md`
|
||||
- `NEXT_STEPS_FINAL_STATUS.md`
|
||||
|
||||
**From `docs/status/` → `docs/archive/status/`:**
|
||||
- `NEXT_STEPS_COMPLETION.md`
|
||||
|
||||
**Script Used**: `scripts/cleanup-archive-old-status.sh`
|
||||
|
||||
---
|
||||
|
||||
### 2. ✅ Large JSON Indexes Configured (Already Ignored)
|
||||
|
||||
Large generated index files are configured to be ignored by git:
|
||||
|
||||
- `docs/MARKDOWN_REFERENCE.json` (5.1 MB) - In .gitignore
|
||||
- `docs/MARKDOWN_INDEX.json` (1.1 MB) - In .gitignore
|
||||
|
||||
**Status**: These files are in `.gitignore` and were never tracked in git. They remain available locally and can be regenerated using:
|
||||
```bash
|
||||
python3 scripts/generate-markdown-reference.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
- **Files Archived**: 48 old status files moved to archive directories
|
||||
- **JSON Index Files**: Configured in `.gitignore` (never tracked, remains local)
|
||||
- **Remaining Old Status Files**: 0 (all archived)
|
||||
- **Disk Space**: Large generated files no longer tracked in git
|
||||
|
||||
---
|
||||
|
||||
## File Status
|
||||
|
||||
### Generated Index Files
|
||||
|
||||
These files are now ignored by git but remain available locally:
|
||||
- ✅ `docs/MARKDOWN_REFERENCE.json` - Available locally, ignored by git
|
||||
- ✅ `docs/MARKDOWN_INDEX.json` - Available locally, ignored by git
|
||||
|
||||
### Archive Directories
|
||||
|
||||
- ✅ `docs/proxmox/archive/` - Contains archived Proxmox status files
|
||||
- ✅ `docs/archive/status/` - Contains archived general status files
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
No further action required. The cleanup is complete!
|
||||
|
||||
To regenerate the index files locally:
|
||||
```bash
|
||||
python3 scripts/generate-markdown-reference.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-09
|
||||
|
||||
253
docs/meta/FILES_TO_PRUNE.md
Normal file
253
docs/meta/FILES_TO_PRUNE.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# Files to Prune
|
||||
|
||||
**Generated**: 2025-01-09
|
||||
**Status**: Analysis Complete
|
||||
|
||||
This document identifies files that can be safely removed from the project to reduce clutter and improve maintainability.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
- **Build Artifacts**: `.next/`, `node_modules/` (excluded by .gitignore, safe to delete locally)
|
||||
- **Large Generated Files**: 2 large JSON index files (6.2MB total)
|
||||
- **Old Status Files**: 14 status files that could be archived
|
||||
- **Duplicate Files**: 4 duplicate file groups
|
||||
- **Archive Files**: 50+ archived files (intentionally kept, but could be reviewed)
|
||||
- **Webpack Cache**: Old webpack cache files
|
||||
|
||||
---
|
||||
|
||||
## 1. Large Generated Index Files (6.2MB total)
|
||||
|
||||
These files are generated by scripts and can be regenerated at any time. Consider removing them from version control and regenerating as needed.
|
||||
|
||||
### Recommended Action: Remove from Git (keep in .gitignore)
|
||||
|
||||
- `docs/MARKDOWN_REFERENCE.json` (5.1 MB) - Machine-readable index
|
||||
- `docs/MARKDOWN_INDEX.json` (1.1 MB) - Intermediate index file
|
||||
|
||||
**Rationale**: These are generated files that can be recreated with `scripts/generate-markdown-reference.py`. They should not be in version control.
|
||||
|
||||
**Action**:
|
||||
```bash
|
||||
# Add to .gitignore
|
||||
echo "docs/MARKDOWN_REFERENCE.json" >> .gitignore
|
||||
echo "docs/MARKDOWN_INDEX.json" >> .gitignore
|
||||
|
||||
# Remove from git (keep locally)
|
||||
git rm --cached docs/MARKDOWN_REFERENCE.json
|
||||
git rm --cached docs/MARKDOWN_INDEX.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Old Status Files (14 files)
|
||||
|
||||
These status files contain historical information and could be moved to archive. However, they may still be referenced.
|
||||
|
||||
### Recommended Action: Review and Archive
|
||||
|
||||
**In `docs/proxmox/status/`**:
|
||||
- `COMPLETE_STATUS.md`
|
||||
- `COMPLETE_STATUS_FINAL.md`
|
||||
- `COMPLETE_STATUS_REPORT.md`
|
||||
- `COMPLETE_SUMMARY.md`
|
||||
- `COMPLETION_SUMMARY.md`
|
||||
- `FINAL_STATUS.md`
|
||||
- `FINAL_STATUS_UPDATE.md`
|
||||
- `NEXT_STEPS_COMPLETED.md`
|
||||
- `TASK_COMPLETION_SUMMARY.md`
|
||||
|
||||
**In `docs/status/implementation/`**:
|
||||
- `ALL_TASKS_COMPLETE.md`
|
||||
- `IMPLEMENTATION_COMPLETE.md`
|
||||
- `NEXT_STEPS_COMPLETE.md`
|
||||
- `NEXT_STEPS_FINAL_STATUS.md`
|
||||
|
||||
**In `docs/status/`**:
|
||||
- `NEXT_STEPS_COMPLETION.md`
|
||||
|
||||
**Action**: Review these files to see if they're still actively referenced. If not, move them to `docs/archive/status/` or `docs/proxmox/archive/`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Duplicate Files (4 groups)
|
||||
|
||||
These files have identical content and should be consolidated.
|
||||
|
||||
### Recommended Action: Remove Duplicates
|
||||
|
||||
1. **Infrastructure Data Files** (3 duplicates):
|
||||
- `public/docs/infrastructure/data/cost_estimates.json` ← Remove (keep `docs/infrastructure/data/cost_estimates.json`)
|
||||
- `public/docs/infrastructure/data/deployment_timeline.json` ← Remove (keep `docs/infrastructure/data/deployment_timeline.json`)
|
||||
- `public/docs/infrastructure/data/compliance_requirements.json` ← Remove (keep `docs/infrastructure/data/compliance_requirements.json`)
|
||||
|
||||
2. **DNS Records Files**:
|
||||
- `cloudflare/dns/sankofa.nexus-records.yaml` vs `cloudflare/dns/d-bis.org-records.yaml`
|
||||
- These appear to be duplicates but may serve different domains. **Review before deletion**.
|
||||
|
||||
---
|
||||
|
||||
## 4. Archive Files (50+ files)
|
||||
|
||||
These files are intentionally archived but could be reviewed for consolidation.
|
||||
|
||||
**Location**: `docs/archive/`
|
||||
|
||||
**Recommendation**: Keep archived files but consider:
|
||||
- Consolidating multiple "COMPLETE" or "COMPLETION" files into single summaries
|
||||
- Creating a single "ARCHIVE_SUMMARY.md" that references all archived content
|
||||
- Compressing old archives into ZIP files
|
||||
|
||||
**Action**: Low priority - these serve historical reference purposes.
|
||||
|
||||
---
|
||||
|
||||
## 5. Build Artifacts (Already in .gitignore)
|
||||
|
||||
These are already excluded from git but may exist locally:
|
||||
|
||||
- `.next/` - Next.js build cache
|
||||
- `node_modules/` - Dependencies (should never be committed)
|
||||
- `dist/` - Build outputs
|
||||
- `build/` - Build outputs
|
||||
|
||||
**Action**: Safe to delete locally, will be regenerated:
|
||||
```bash
|
||||
# Clean build artifacts
|
||||
rm -rf .next node_modules dist build coverage
|
||||
pnpm install # Regenerate dependencies
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Webpack Cache Files
|
||||
|
||||
Old webpack cache files that are no longer needed:
|
||||
|
||||
- `.next/cache/webpack/client-development/index.pack.gz.old`
|
||||
- `.next/cache/webpack/server-development/index.pack.gz.old`
|
||||
- `portal/.next/cache/webpack/client-development/index.pack.gz.old`
|
||||
- `portal/.next/cache/webpack/server-development/index.pack.gz.old`
|
||||
|
||||
**Action**: Safe to delete - these are cache files:
|
||||
```bash
|
||||
find . -name "*.old" -path "*/.next/cache/*" -delete
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Large ZIP Archive
|
||||
|
||||
- `docs/6g_gpu_full_package.zip` - Large binary file in docs directory
|
||||
|
||||
**Action**:
|
||||
- If needed for documentation, move to a separate downloads/assets directory
|
||||
- If not needed, delete
|
||||
- Consider hosting externally or in a release artifacts repository
|
||||
|
||||
---
|
||||
|
||||
## 8. Node Modules Lock Files (Already Handled)
|
||||
|
||||
Found several `yarn.lock` files in `node_modules/`:
|
||||
- These are from dependencies and are fine
|
||||
- Main project uses `pnpm-lock.yaml` (correct)
|
||||
|
||||
**Action**: No action needed - these are dependency lock files.
|
||||
|
||||
---
|
||||
|
||||
## 9. Backup Files (Already in .gitignore)
|
||||
|
||||
Found one backup file in node_modules:
|
||||
- `api/node_modules/.pnpm/form-data@2.3.3/node_modules/form-data/README.md.bak`
|
||||
|
||||
**Action**: This is in node_modules, so it's fine. No action needed.
|
||||
|
||||
---
|
||||
|
||||
## Immediate Action Items (High Priority)
|
||||
|
||||
1. **Remove large JSON index files from git** (6.2MB)
|
||||
2. **Remove duplicate infrastructure data files** (3 files)
|
||||
3. **Clean webpack cache files** (4 `.old` files)
|
||||
4. **Review and archive old status files** (14 files)
|
||||
|
||||
---
|
||||
|
||||
## Cleanup Scripts
|
||||
|
||||
Two cleanup scripts have been created to automate the pruning process:
|
||||
|
||||
### 1. Basic Cleanup Script (`scripts/cleanup-prune-files.sh`)
|
||||
|
||||
Removes duplicate files and cache artifacts.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Dry run (see what would be deleted)
|
||||
./scripts/cleanup-prune-files.sh --dry-run
|
||||
|
||||
# Run cleanup (with optional backup)
|
||||
./scripts/cleanup-prune-files.sh --backup
|
||||
./scripts/cleanup-prune-files.sh --all
|
||||
|
||||
# Specific operations
|
||||
./scripts/cleanup-prune-files.sh --duplicates # Remove duplicates only
|
||||
./scripts/cleanup-prune-files.sh --cache # Remove cache files only
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
- Removes duplicate infrastructure data files from `public/`
|
||||
- Removes webpack cache `.old` files
|
||||
- Optional backup creation before deletion
|
||||
- Dry-run mode for safety
|
||||
|
||||
### 2. Archive Old Status Files (`scripts/cleanup-archive-old-status.sh`)
|
||||
|
||||
Moves old status files to archive directories.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Dry run (see what would be moved)
|
||||
./scripts/cleanup-archive-old-status.sh --dry-run
|
||||
|
||||
# Actually move files
|
||||
./scripts/cleanup-archive-old-status.sh
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
- Moves old status files from `docs/proxmox/status/` to `docs/proxmox/archive/`
|
||||
- Moves old status files from `docs/status/implementation/` to `docs/archive/status/`
|
||||
- Preserves file structure in archive
|
||||
|
||||
---
|
||||
|
||||
## Files to Keep
|
||||
|
||||
**DO NOT DELETE**:
|
||||
- Archive files in `docs/archive/` (historical reference)
|
||||
- Status files that are actively referenced
|
||||
- Documentation files (even if old)
|
||||
- Configuration files
|
||||
- Source code files
|
||||
|
||||
---
|
||||
|
||||
## Recommendations Summary
|
||||
|
||||
| Category | Count | Priority | Action |
|
||||
|----------|-------|----------|--------|
|
||||
| Large JSON indexes | 2 | **High** | Remove from git, add to .gitignore |
|
||||
| Duplicate files | 4 groups | **Medium** | Remove duplicates |
|
||||
| Old status files | 14 | **Medium** | Review and archive |
|
||||
| Webpack cache | 4 | **Low** | Delete |
|
||||
| Large ZIP file | 1 | **Low** | Review and relocate/delete |
|
||||
| Archive files | 50+ | **None** | Keep (historical) |
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-09
|
||||
|
||||
225
docs/meta/MARKDOWN_DEDUPLICATION_REPORT.md
Normal file
225
docs/meta/MARKDOWN_DEDUPLICATION_REPORT.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# Markdown Deduplication and Reorganization Report
|
||||
|
||||
**Date**: 2025-01-09
|
||||
**Status**: Analysis Complete
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This report documents the deduplication and reorganization of Markdown files across the project. Analysis identified **1 exact duplicate** and several files with similar purposes that may benefit from consolidation.
|
||||
|
||||
### Actions Taken
|
||||
|
||||
1. ✅ **Removed Exact Duplicate**: `docs/status/implementation/CLEANUP_SUMMARY.md` (duplicate of `docs/archive/CLEANUP_SUMMARY.md`)
|
||||
2. ✅ **Generated Comprehensive Index**: Created `docs/MARKDOWN_REFERENCE.json` with detailed mapping
|
||||
3. ✅ **Created Reference Guide**: Generated `docs/MARKDOWN_REFERENCE.md` for human-readable navigation
|
||||
|
||||
---
|
||||
|
||||
## Duplicate Files Removed
|
||||
|
||||
### Exact Duplicates (Content Hash Match)
|
||||
|
||||
1. **Removed**: `docs/status/implementation/CLEANUP_SUMMARY.md`
|
||||
- **Reason**: Identical to `docs/archive/CLEANUP_SUMMARY.md`
|
||||
- **Action**: Deleted duplicate, kept archived version
|
||||
|
||||
---
|
||||
|
||||
## Similar Content Analysis
|
||||
|
||||
### Files with Similar Titles/Purposes
|
||||
|
||||
The following files have similar purposes but are NOT exact duplicates. They serve different contexts:
|
||||
|
||||
#### Audit Reports
|
||||
|
||||
- `docs/AUDIT_SUMMARY.md` - Quick reference summary (KEEP)
|
||||
- `docs/REPOSITORY_AUDIT_REPORT.md` - Comprehensive repository audit (KEEP)
|
||||
- `docs/COMPREHENSIVE_AUDIT_REPORT.md` - General comprehensive audit (KEEP)
|
||||
- `docs/PROXMOX_COMPREHENSIVE_AUDIT_REPORT.md` - Proxmox-specific audit (KEEP)
|
||||
- `docs/archive/audits/*` - Historical audit reports (KEEP - archived)
|
||||
|
||||
**Recommendation**: These serve different purposes. `AUDIT_SUMMARY.md` is a quick reference, while others are detailed reports.
|
||||
|
||||
#### Review Reports
|
||||
|
||||
- `docs/PROJECT_COMPREHENSIVE_REVIEW.md` - Complete project review (KEEP - active)
|
||||
- `docs/REVIEW_ITEMS_COMPLETED.md` - Summary of completed review items (KEEP - active)
|
||||
- `docs/archive/*` - Historical review reports (KEEP - archived)
|
||||
|
||||
**Recommendation**: Active review files serve current purposes. Archived files are historical.
|
||||
|
||||
#### Status Reports
|
||||
|
||||
Multiple status reports exist in different contexts:
|
||||
- `docs/status/*` - Current status reports (KEEP - active)
|
||||
- `docs/proxmox/status/*` - Proxmox-specific status (KEEP - organized by topic)
|
||||
- `docs/archive/status/*` - Historical status (KEEP - archived)
|
||||
|
||||
**Recommendation**: Current organization is logical. Status files are properly categorized.
|
||||
|
||||
#### API Documentation
|
||||
|
||||
- `docs/API_DOCUMENTATION.md` - General API documentation (KEEP)
|
||||
- `docs/api/README.md` - API directory index (KEEP)
|
||||
- `docs/infrastructure/API_DOCUMENTATION.md` - Infrastructure API docs (KEEP - different scope)
|
||||
|
||||
**Recommendation**: These serve different purposes. No consolidation needed.
|
||||
|
||||
---
|
||||
|
||||
## Reference Index Generated
|
||||
|
||||
### Files Created
|
||||
|
||||
1. **`docs/MARKDOWN_REFERENCE.json`**
|
||||
- Comprehensive JSON index mapping all Markdown files
|
||||
- Includes: headings, sections, code references, links, line numbers
|
||||
- Machine-readable format for tools and automation
|
||||
|
||||
2. **`docs/MARKDOWN_REFERENCE.md`**
|
||||
- Human-readable reference guide
|
||||
- Organized by category
|
||||
- Includes heading index and file details
|
||||
|
||||
### Index Structure
|
||||
|
||||
The reference index includes:
|
||||
|
||||
- **By File**: Complete mapping of each file with:
|
||||
- Title and metadata
|
||||
- All headings with line numbers
|
||||
- Sections with content preview
|
||||
- Code references
|
||||
- Cross-references to other files
|
||||
|
||||
- **By Heading**: Index of all headings across all files with:
|
||||
- File location
|
||||
- Line number
|
||||
- Heading level
|
||||
|
||||
- **By Category**: Files grouped by location/category
|
||||
|
||||
- **Cross-References**: Links between Markdown files
|
||||
|
||||
---
|
||||
|
||||
## File Organization Assessment
|
||||
|
||||
### Current Structure
|
||||
|
||||
The documentation is well-organized:
|
||||
|
||||
```
|
||||
docs/
|
||||
├── api/ # API documentation
|
||||
├── architecture/ # Architecture docs
|
||||
├── archive/ # Historical docs
|
||||
│ ├── audits/ # Archived audit reports
|
||||
│ └── status/ # Archived status reports
|
||||
├── brand/ # Brand documentation
|
||||
├── compliance/ # Compliance docs
|
||||
├── proxmox/ # Proxmox-specific docs
|
||||
│ ├── guides/ # How-to guides
|
||||
│ ├── reference/ # Reference materials
|
||||
│ ├── status/ # Status reports
|
||||
│ └── archive/ # Archived Proxmox docs
|
||||
├── runbooks/ # Operational runbooks
|
||||
├── status/ # Current status reports
|
||||
└── [root level docs] # Top-level documentation
|
||||
```
|
||||
|
||||
### Organization Quality: ✅ **EXCELLENT**
|
||||
|
||||
- Clear separation by topic (proxmox, api, architecture)
|
||||
- Proper archival of historical content
|
||||
- Logical subdirectories (guides, reference, status)
|
||||
- Index files for navigation
|
||||
|
||||
**Recommendation**: Current organization is excellent. No major reorganization needed.
|
||||
|
||||
---
|
||||
|
||||
## Statistics
|
||||
|
||||
- **Total Markdown Files**: 279
|
||||
- **Unique Files**: 278 (after removing 1 duplicate)
|
||||
- **Files by Category**:
|
||||
- `docs/`: 252 files
|
||||
- Root level: 3 files
|
||||
- API: ~5 files
|
||||
- Portal: 1 file
|
||||
- Scripts: 2 files
|
||||
- Other: 16 files
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Immediate Actions (Completed)
|
||||
|
||||
1. ✅ Removed exact duplicate file
|
||||
2. ✅ Generated comprehensive index
|
||||
3. ✅ Created reference mapping
|
||||
|
||||
### Future Considerations
|
||||
|
||||
1. **Consolidation Opportunities** (Low Priority):
|
||||
- Consider consolidating some Proxmox status reports if they become redundant
|
||||
- Monitor for future duplicate creation
|
||||
|
||||
2. **Maintenance**:
|
||||
- Use `scripts/analyze-markdown.py` periodically to check for new duplicates
|
||||
- Keep reference index updated as documentation evolves
|
||||
|
||||
3. **Documentation Standards**:
|
||||
- All new documentation should follow existing structure
|
||||
- Use index files (`README.md`) in each directory for navigation
|
||||
|
||||
---
|
||||
|
||||
## Tools Created
|
||||
|
||||
1. **`scripts/analyze-markdown.py`**
|
||||
- Finds duplicate files by content hash
|
||||
- Analyzes file structure and organization
|
||||
- Identifies similar content
|
||||
|
||||
2. **`scripts/generate-markdown-reference.py`**
|
||||
- Generates comprehensive reference index
|
||||
- Maps content to files and line numbers
|
||||
- Creates cross-reference mapping
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
### Finding Content
|
||||
|
||||
Use the reference index to find specific content:
|
||||
|
||||
```bash
|
||||
# Search in JSON index
|
||||
cat docs/MARKDOWN_REFERENCE.json | jq '.by_heading["your heading"]'
|
||||
|
||||
# View human-readable report
|
||||
cat docs/MARKDOWN_REFERENCE.md
|
||||
|
||||
# Re-run analysis
|
||||
python3 scripts/analyze-markdown.py
|
||||
```
|
||||
|
||||
### Updating Index
|
||||
|
||||
The index can be regenerated anytime:
|
||||
|
||||
```bash
|
||||
python3 scripts/generate-markdown-reference.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-09
|
||||
|
||||
128
docs/meta/MARKDOWN_INDEX_README.md
Normal file
128
docs/meta/MARKDOWN_INDEX_README.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# Markdown Documentation Index
|
||||
|
||||
**Last Updated**: 2025-01-09
|
||||
|
||||
This directory contains comprehensive indexes and analysis of all Markdown documentation in the Sankofa Phoenix project.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Index Files
|
||||
|
||||
1. **[MARKDOWN_REFERENCE.md](./MARKDOWN_REFERENCE.md)**
|
||||
- Human-readable index of all Markdown files
|
||||
- Organized by category
|
||||
- Includes headings, line numbers, and file details
|
||||
|
||||
2. **[MARKDOWN_REFERENCE.json](./MARKDOWN_REFERENCE.json)**
|
||||
- Machine-readable comprehensive index (186KB)
|
||||
- Detailed mapping of content to files and line numbers
|
||||
- Includes: headings, sections, code references, links, cross-references
|
||||
|
||||
3. **[MARKDOWN_DEDUPLICATION_REPORT.md](./MARKDOWN_DEDUPLICATION_REPORT.md)**
|
||||
- Analysis of duplicate and similar content
|
||||
- Recommendations for consolidation
|
||||
- Organization assessment
|
||||
|
||||
---
|
||||
|
||||
## Statistics
|
||||
|
||||
- **Total Markdown Files**: 279
|
||||
- **Unique Files**: 278 (1 duplicate removed)
|
||||
- **Total Headings Indexed**: 6,439
|
||||
- **Cross-References**: 498 links between files
|
||||
- **Categories**: 9 main categories
|
||||
|
||||
### Files by Category
|
||||
|
||||
- `docs/`: 113 files (root level documentation)
|
||||
- `proxmox/`: 53 files (Proxmox-specific documentation)
|
||||
- `archive/`: 50 files (historical/archived documentation)
|
||||
- `status/`: 18 files (status reports)
|
||||
- `other/`: 26 files (miscellaneous locations)
|
||||
- `architecture/`: 6 files (architecture documentation)
|
||||
- `runbooks/`: 7 files (operational runbooks)
|
||||
- `api/`: 4 files (API documentation)
|
||||
- `portal/`: 1 file (Portal documentation)
|
||||
|
||||
---
|
||||
|
||||
## Most Common Headings
|
||||
|
||||
1. "Overview" - 82 occurrences
|
||||
2. "Related Documentation" - 76 occurrences
|
||||
3. "Next Steps" - 75 occurrences
|
||||
4. "Troubleshooting" - 48 occurrences
|
||||
5. "Summary" - 37 occurrences
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
### Find Content by Heading
|
||||
|
||||
```bash
|
||||
# Search in JSON index
|
||||
cat docs/MARKDOWN_REFERENCE.json | jq '.by_heading["your heading"]'
|
||||
|
||||
# Example: Find all files with "deployment" heading
|
||||
cat docs/MARKDOWN_REFERENCE.json | jq '.by_heading | to_entries | map(select(.key | contains("deployment")))'
|
||||
```
|
||||
|
||||
### Find Files by Category
|
||||
|
||||
```bash
|
||||
# List all files in a category
|
||||
cat docs/MARKDOWN_REFERENCE.json | jq '.by_category["proxmox"]'
|
||||
```
|
||||
|
||||
### Find Cross-References
|
||||
|
||||
```bash
|
||||
# Find all files that link to a specific file
|
||||
cat docs/MARKDOWN_REFERENCE.json | jq '.cross_references | to_entries | map(select(.value[].target | contains("DEPLOYMENT.md")))'
|
||||
```
|
||||
|
||||
### View File Details
|
||||
|
||||
```bash
|
||||
# Get detailed information about a specific file
|
||||
cat docs/MARKDOWN_REFERENCE.json | jq '.by_file["docs/DEPLOYMENT.md"]'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Regenerating the Index
|
||||
|
||||
To regenerate the index after adding/modifying Markdown files:
|
||||
|
||||
```bash
|
||||
# Run the analysis script
|
||||
python3 scripts/analyze-markdown.py
|
||||
|
||||
# Generate the reference mapping
|
||||
python3 scripts/generate-markdown-reference.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tools
|
||||
|
||||
1. **`scripts/analyze-markdown.py`**
|
||||
- Finds duplicate files by content hash
|
||||
- Analyzes file structure
|
||||
- Identifies similar content
|
||||
|
||||
2. **`scripts/generate-markdown-reference.py`**
|
||||
- Generates comprehensive reference index
|
||||
- Maps content to files and line numbers
|
||||
- Creates cross-reference mapping
|
||||
|
||||
---
|
||||
|
||||
**See Also**:
|
||||
- [Documentation README](./README.md) - Main documentation index
|
||||
- [Deduplication Report](./MARKDOWN_DEDUPLICATION_REPORT.md) - Detailed analysis
|
||||
|
||||
135
docs/meta/ORGANIZATION.md
Normal file
135
docs/meta/ORGANIZATION.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# Documentation Organization
|
||||
|
||||
**Last Updated**: 2025-01-09
|
||||
|
||||
This document describes the organization structure of documentation in the `docs/` directory.
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
docs/
|
||||
├── guides/ # Step-by-step guides and how-to documentation
|
||||
├── reference/ # Reference materials and specifications
|
||||
├── reports/ # Audit reports, reviews, and analysis
|
||||
├── summaries/ # Completion and implementation summaries
|
||||
├── deployment/ # Deployment status and planning
|
||||
├── vm/ # Virtual Machine documentation
|
||||
├── guest-agent/ # Guest agent documentation
|
||||
├── api/ # API documentation
|
||||
├── architecture/ # Architecture documentation
|
||||
├── archive/ # Historical/archived documentation
|
||||
├── proxmox/ # Proxmox-specific documentation
|
||||
├── status/ # Current status reports
|
||||
├── runbooks/ # Operational runbooks
|
||||
├── brand/ # Brand documentation
|
||||
├── compliance/ # Compliance documentation
|
||||
└── [root files] # Top-level documentation and indexes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Root Directory Files
|
||||
|
||||
The `docs/` root contains:
|
||||
|
||||
### Index Files
|
||||
- `README.md` - Main documentation index
|
||||
- `ARCHITECTURE_INDEX.md` - Architecture documentation index
|
||||
- `DEPLOYMENT_INDEX.md` - Deployment documentation index
|
||||
- `GUIDES_INDEX.md` - Guides index
|
||||
- `REFERENCE_INDEX.md` - Reference documentation index
|
||||
|
||||
### Core Documentation
|
||||
- `DEPLOYMENT.md` - Main deployment guide
|
||||
- `DEPLOYMENT_REQUIREMENTS.md` - Deployment requirements
|
||||
- `DEPLOYMENT_EXECUTION_PLAN.md` - Deployment execution plan
|
||||
- `API_DOCUMENTATION.md` - API documentation
|
||||
- `DEVELOPMENT.md` - Development guide
|
||||
- `TESTING.md` - Testing guide
|
||||
- `CONTRIBUTING.md` - Contributing guidelines
|
||||
- `TROUBLESHOOTING_GUIDE.md` - Troubleshooting guide
|
||||
- `MONITORING_GUIDE.md` - Monitoring guide
|
||||
- `OPERATIONS_RUNBOOK.md` - Operations runbook
|
||||
- `KEYCLOAK_DEPLOYMENT.md` - Keycloak deployment guide
|
||||
- `MIGRATION_GUIDE.md` - Migration guide
|
||||
- `DESIGN_SYSTEM.md` - Design system
|
||||
- `ENTERPRISE_ARCHITECTURE.md` - Enterprise architecture
|
||||
- `PNPM_MIGRATION_GUIDE.md` - pnpm migration guide
|
||||
|
||||
### Index Files
|
||||
- `MARKDOWN_REFERENCE.md` - Markdown reference index
|
||||
- `MARKDOWN_REFERENCE.json` - Machine-readable index
|
||||
- `MARKDOWN_DEDUPLICATION_REPORT.md` - Deduplication report
|
||||
- `MARKDOWN_INDEX_README.md` - Index usage guide
|
||||
|
||||
---
|
||||
|
||||
## Organized Directories
|
||||
|
||||
### guides/
|
||||
Step-by-step guides and how-to documentation.
|
||||
|
||||
- `BUILD_AND_DEPLOY_INSTRUCTIONS.md`
|
||||
- `FORCE_UNLOCK_INSTRUCTIONS.md`
|
||||
- `QUICK_INSTALL_GUEST_AGENT.md`
|
||||
- `enable-guest-agent-manual.md`
|
||||
|
||||
### reference/
|
||||
Reference materials, specifications, and technical details.
|
||||
|
||||
- `CODE_INCONSISTENCIES.md`
|
||||
- `COPY_SCRIPT_TO_PROXMOX_NODES.md`
|
||||
- `SCRIPT_COPIED_TO_PROXMOX_NODES.md`
|
||||
|
||||
### reports/
|
||||
Audit reports, review reports, and analysis documents.
|
||||
|
||||
- `AUDIT_SUMMARY.md`
|
||||
- `COMPREHENSIVE_AUDIT_REPORT.md`
|
||||
- `PROXMOX_COMPREHENSIVE_AUDIT_REPORT.md`
|
||||
- `REPOSITORY_AUDIT_REPORT.md`
|
||||
- `PROJECT_COMPREHENSIVE_REVIEW.md`
|
||||
- `REVIEW_ITEMS_COMPLETED.md`
|
||||
- `DOCUMENTATION_DEEP_DIVE_ANALYSIS.md`
|
||||
- `DOCUMENTATION_FIXES_APPLIED.md`
|
||||
|
||||
### summaries/
|
||||
Completion summaries and implementation summaries.
|
||||
|
||||
- `DOCUMENTATION_COMPLETE_SUMMARY.md`
|
||||
- `IMPLEMENTATION_SUMMARY.md`
|
||||
|
||||
### deployment/
|
||||
Deployment-related status and planning documents.
|
||||
|
||||
- `DEPLOYMENT_NEXT_STEPS.md`
|
||||
- `DEPLOYMENT_READY.md`
|
||||
- `PRE_DEPLOYMENT_CHECKLIST.md`
|
||||
|
||||
### vm/
|
||||
Virtual Machine (VM) related documentation.
|
||||
|
||||
- `VM_CREATION_PROCEDURE.md`
|
||||
- `VM_DEPLOYMENT_CHECKLIST.md`
|
||||
- `VM_SPECIFICATIONS.md`
|
||||
|
||||
### guest-agent/
|
||||
Guest agent implementation and configuration documentation.
|
||||
|
||||
- `GUEST_AGENT_CHECKLIST.md`
|
||||
- `GUEST_AGENT_CONFIGURATION_ANALYSIS.md`
|
||||
|
||||
---
|
||||
|
||||
## Navigation
|
||||
|
||||
- Use the index files (`*_INDEX.md`) for navigation
|
||||
- Check `README.md` in each directory for contents
|
||||
- Use [Markdown Reference Index](./MARKDOWN_REFERENCE.md) for comprehensive search
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-09
|
||||
|
||||
17
docs/meta/README.md
Normal file
17
docs/meta/README.md
Normal file
@@ -0,0 +1,17 @@
|
||||
# Documentation Metadata
|
||||
|
||||
This directory contains metadata, cleanup reports, and organizational documentation about the docs directory itself.
|
||||
|
||||
## Contents
|
||||
|
||||
- **CLEANUP_COMPLETE.md** - Summary of cleanup operations
|
||||
- **CLEANUP_NEXT_STEPS_COMPLETE.md** - Completion of cleanup next steps
|
||||
- **FILES_TO_PRUNE.md** - Analysis of files that can be pruned
|
||||
- **ORGANIZATION.md** - Guide to documentation structure and organization
|
||||
- **MARKDOWN_DEDUPLICATION_REPORT.md** - Analysis of markdown deduplication
|
||||
- **MARKDOWN_INDEX_README.md** - Usage guide for markdown index files
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-09
|
||||
|
||||
Reference in New Issue
Block a user