From 51acaf716d68ba8087696e67a712af1f9aa808b1 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 9 Nov 2025 01:17:47 +0000 Subject: [PATCH] docs: Reorganize and clean up documentation structure Comprehensive documentation cleanup and reorganization: Added: - docs/README.md - Complete documentation index with: - Table of contents organized by category - Quick start guide for documentation - Finding information by topic and task - Documentation standards - Recent updates tracking Reorganized: - docs/guides/ - Core documentation (testing, troubleshooting, Docker, scripts) - testing-guide.md - Test framework and running tests - troubleshooting.md - Common issues and solutions - docker-testing.md - Docker testing modes and usage - script-reference.md - Complete script documentation - docs/setup/ - Tool setup guides - serena-setup.md - Serena coding agent setup - context7-setup.md - Context7 documentation setup - qwen-setup.md - Qwen CLI with Ollama - docs/mcp/ - MCP server documentation - mcp-server-status.md - Server status tracking - claude-to-gemini-mcp-migration.md - Gemini MCP usage - github-mcp-setup.md - GitHub integration - memorybank-mcp-setup.md - Memory persistence - MCP-MIGRATION-SUMMARY.md - Historical migration notes Updated: - MCP-MIGRATION-SUMMARY.md - Added note that migration is complete and scripts are archived - README.md - Updated all doc references to new paths - CONTRIBUTING.md - Updated doc path references Benefits: - Clear organization by purpose (guides/setup/mcp) - Easier to find relevant documentation - Comprehensive index for navigation - Better maintainability - Clearer separation of concerns All internal links updated to reflect new structure. --- CONTRIBUTING.md | 2 +- README.md | 21 +- docs/README.md | 191 ++++++++++++++++++ docs/{ => guides}/docker-testing.md | 0 docs/{ => guides}/script-reference.md | 0 docs/{ => guides}/testing-guide.md | 0 docs/{ => guides}/troubleshooting.md | 0 docs/{ => mcp}/MCP-MIGRATION-SUMMARY.md | 4 + .../claude-to-gemini-mcp-migration.md | 0 docs/{ => mcp}/github-mcp-setup.md | 0 docs/{ => mcp}/mcp-server-status.md | 0 docs/{ => mcp}/memorybank-mcp-setup.md | 0 docs/{ => setup}/context7-setup.md | 0 docs/{ => setup}/qwen-setup.md | 0 docs/{ => setup}/serena-setup.md | 0 15 files changed, 208 insertions(+), 10 deletions(-) create mode 100644 docs/README.md rename docs/{ => guides}/docker-testing.md (100%) rename docs/{ => guides}/script-reference.md (100%) rename docs/{ => guides}/testing-guide.md (100%) rename docs/{ => guides}/troubleshooting.md (100%) rename docs/{ => mcp}/MCP-MIGRATION-SUMMARY.md (93%) rename docs/{ => mcp}/claude-to-gemini-mcp-migration.md (100%) rename docs/{ => mcp}/github-mcp-setup.md (100%) rename docs/{ => mcp}/mcp-server-status.md (100%) rename docs/{ => mcp}/memorybank-mcp-setup.md (100%) rename docs/{ => setup}/context7-setup.md (100%) rename docs/{ => setup}/qwen-setup.md (100%) rename docs/{ => setup}/serena-setup.md (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ed2a8a0..f313d91 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -420,7 +420,7 @@ make docs-preview # (coming soon) ## Questions or Problems? - **Documentation**: Check `docs/` directory -- **Troubleshooting**: See `docs/troubleshooting.md` +- **Troubleshooting**: See `docs/guides/troubleshooting.md` - **Issues**: Open an issue on GitHub - **Discussions**: Use GitHub Discussions diff --git a/README.md b/README.md index f98916a..f1fc6aa 100644 --- a/README.md +++ b/README.md @@ -162,12 +162,15 @@ serena-init [project_name] [project_path] ## 📚 Documentation -- **[Testing Guide](docs/testing-guide.md)** - How to write and run tests -- **[Troubleshooting Guide](docs/troubleshooting.md)** - Common issues and solutions -- [MCP Server Status](docs/mcp-server-status.md) - Current status of all MCP servers -- [Serena Setup Guide](docs/serena-setup.md) - Complete Serena documentation -- [Context7 Setup Guide](docs/context7-setup.md) - Context7 documentation -- [Qwen Setup Guide](docs/qwen-setup.md) - Qwen CLI with Ollama integration +- **[Documentation Index](docs/)** - Complete documentation index + +- **[Testing Guide](docs/guides/testing-guide.md)** - How to write and run tests +- **[Troubleshooting Guide](docs/guides/troubleshooting.md)** - Common issues and solutions +- **[Docker Testing Guide](docs/guides/docker-testing.md)** - Testing in isolated containers +- [MCP Server Status](docs/mcp/mcp-server-status.md) - Current status of all MCP servers +- [Serena Setup Guide](docs/setup/serena-setup.md) - Complete Serena documentation +- [Context7 Setup Guide](docs/setup/context7-setup.md) - Context7 documentation +- [Qwen Setup Guide](docs/setup/qwen-setup.md) - Qwen CLI with Ollama integration ## Testing @@ -195,7 +198,7 @@ The repository includes a comprehensive testing framework to ensure reliability. ./scripts/cleanup-failing-mcps.sh ``` -See [Testing Guide](docs/testing-guide.md) for details on writing and running tests. +See [Testing Guide](docs/guides/testing-guide.md) for details on writing and running tests. ## 🔧 Development @@ -275,7 +278,7 @@ ENVIRONMENT VARIABLES: ## 🐛 Troubleshooting -See the comprehensive [Troubleshooting Guide](docs/troubleshooting.md) for common issues and solutions. +See the comprehensive [Troubleshooting Guide](docs/guides/troubleshooting.md) for common issues and solutions. Quick tips: - **Installation fails**: Check `~/.dotfiles-install.log` @@ -461,5 +464,5 @@ make docker-shell - Manual testing - Explore environment -See [Docker Testing Guide](docs/docker-testing.md) for complete documentation. +See [Docker Testing Guide](docs/guides/docker-testing.md) for complete documentation. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..7c98ca9 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,191 @@ +# Documentation Index + +Welcome to the dotfiles documentation! This directory contains comprehensive guides for installation, configuration, testing, and troubleshooting. + +## 📚 Table of Contents + +### Quick Start Guides + +- **[Testing Guide](guides/testing-guide.md)** - How to write and run tests +- **[Troubleshooting Guide](guides/troubleshooting.md)** - Common issues and solutions +- **[Docker Testing Guide](guides/docker-testing.md)** - Testing in isolated containers + +### Reference Documentation + +- **[Script Reference](guides/script-reference.md)** - Complete reference for all scripts and utilities + +### Tool Setup Guides + +#### AI Coding Assistants + +- **[Serena Setup](setup/serena-setup.md)** - Coding agent with web dashboard and language servers +- **[Context7 Setup](setup/context7-setup.md)** - Code documentation and context generation +- **[Qwen Setup](setup/qwen-setup.md)** - Qwen CLI with Ollama integration + +#### MCP (Model Context Protocol) Servers + +- **[MCP Server Status](mcp/mcp-server-status.md)** - Current status of all MCP servers +- **[Claude to Gemini MCP Migration](mcp/claude-to-gemini-mcp-migration.md)** - Using MCP with Gemini CLI +- **[GitHub MCP Setup](mcp/github-mcp-setup.md)** - GitHub integration via MCP +- **[MemoryBank MCP Setup](mcp/memorybank-mcp-setup.md)** - Memory and context persistence + +## 🚀 Getting Started + +New to this repository? Start here: + +1. Read the main [README.md](../README.md) for an overview +2. Review the [Testing Guide](guides/testing-guide.md) to understand the test framework +3. Check the [Troubleshooting Guide](guides/troubleshooting.md) if you encounter issues +4. Explore [Tool Setup Guides](#tool-setup-guides) for specific tools + +## 📖 Documentation Organization + +### Core Guides (`guides/`) + +**testing-guide.md** +- Test framework overview +- Writing tests +- Running tests locally and in CI +- Test suite organization + +**troubleshooting.md** +- Installation issues +- Shell configuration problems +- Tool-specific fixes +- Performance optimization +- Testing and CI problems + +**docker-testing.md** +- Docker test modes (quick, full, multi-distro) +- Container setup and configuration +- CI integration +- Advanced usage and debugging + +**script-reference.md** +- Complete script documentation +- Usage examples +- Options and flags +- Common workflows + +### Setup Guides (`setup/`) + +**serena-setup.md** +- Installation and configuration +- Web dashboard setup +- Language server integration +- Usage examples + +**context7-setup.md** +- Project initialization +- Workspace configuration +- Advanced indexing +- Troubleshooting + +**qwen-setup.md** +- Ollama integration +- Model configuration +- CLI usage +- Performance tuning + +### MCP Documentation (`mcp/`) + +**mcp-server-status.md** +- List of all configured MCP servers +- Server status and health +- Known issues +- Update information + +**claude-to-gemini-mcp-migration.md** +- Configuration differences +- Migration steps +- Server compatibility +- Testing and validation + +**github-mcp-setup.md** +- GitHub MCP server setup +- Authentication and tokens +- Available operations +- Usage examples + +**memorybank-mcp-setup.md** +- Memory persistence setup +- Context management +- Configuration options +- Best practices + +## 🔍 Finding Information + +### By Topic + +- **Installation**: See main [README.md](../README.md) and [guides/troubleshooting.md](guides/troubleshooting.md) +- **Testing**: See [guides/testing-guide.md](guides/testing-guide.md) and [guides/docker-testing.md](guides/docker-testing.md) +- **Scripts**: See [guides/script-reference.md](guides/script-reference.md) +- **AI Tools**: See individual setup guides under [Tool Setup Guides](#tool-setup-guides) +- **MCP Servers**: See docs under [MCP Documentation](#mcp-documentation) + +### By Task + +| Task | Documentation | +|------|---------------| +| Running tests | [guides/testing-guide.md](guides/testing-guide.md) | +| Testing in Docker | [guides/docker-testing.md](guides/docker-testing.md) | +| Fixing installation issues | [guides/troubleshooting.md](guides/troubleshooting.md) | +| Setting up Serena | [setup/serena-setup.md](setup/serena-setup.md) | +| Setting up Context7 | [setup/context7-setup.md](setup/context7-setup.md) | +| Configuring MCP servers | [mcp/mcp-server-status.md](mcp/mcp-server-status.md) | +| Using scripts | [guides/script-reference.md](guides/script-reference.md) | +| Contributing | [../CONTRIBUTING.md](../CONTRIBUTING.md) | + +## 📝 Documentation Standards + +All documentation in this directory follows these standards: + +### Structure +- Clear title and overview +- Table of contents for docs >100 lines +- Organized sections with headers +- Examples and code blocks +- Troubleshooting section (where applicable) + +### Formatting +- Markdown format +- Code blocks with language tags +- Links to related documentation +- Consistent header hierarchy + +### Maintenance +- Keep documentation in sync with code +- Update version-specific information +- Remove outdated content +- Add dates to time-sensitive information + +## 🤝 Contributing to Documentation + +To improve this documentation: + +1. Follow the documentation standards above +2. Test all commands and examples +3. Add screenshots where helpful (not required) +4. Update this index when adding new docs +5. Link to related documentation +6. Run spell check before committing + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for general contribution guidelines. + +## 📅 Recent Updates + +- **2025-11-08**: Added comprehensive documentation cleanup +- **2025-11-08**: Added Docker testing guide +- **2025-11-08**: Created documentation index + +## 🔗 External Resources + +- [Anthropic Claude Documentation](https://docs.anthropic.com/) +- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) +- [Starship Prompt](https://starship.rs/) +- [Tmux Documentation](https://github.com/tmux/tmux/wiki) +- [Yazi File Manager](https://yazi-rs.github.io/) + +--- + +**Navigation**: [Main README](../README.md) | [Contributing](../CONTRIBUTING.md) | [Changelog](../CHANGELOG.md) diff --git a/docs/docker-testing.md b/docs/guides/docker-testing.md similarity index 100% rename from docs/docker-testing.md rename to docs/guides/docker-testing.md diff --git a/docs/script-reference.md b/docs/guides/script-reference.md similarity index 100% rename from docs/script-reference.md rename to docs/guides/script-reference.md diff --git a/docs/testing-guide.md b/docs/guides/testing-guide.md similarity index 100% rename from docs/testing-guide.md rename to docs/guides/testing-guide.md diff --git a/docs/troubleshooting.md b/docs/guides/troubleshooting.md similarity index 100% rename from docs/troubleshooting.md rename to docs/guides/troubleshooting.md diff --git a/docs/MCP-MIGRATION-SUMMARY.md b/docs/mcp/MCP-MIGRATION-SUMMARY.md similarity index 93% rename from docs/MCP-MIGRATION-SUMMARY.md rename to docs/mcp/MCP-MIGRATION-SUMMARY.md index 24f97f5..50694f9 100644 --- a/docs/MCP-MIGRATION-SUMMARY.md +++ b/docs/mcp/MCP-MIGRATION-SUMMARY.md @@ -1,9 +1,13 @@ # MCP Migration Summary +> **Note**: This document is historical. The migration described below has been completed. The migration scripts mentioned (`migrate-to-mcp-json.sh`, `test-mcp-json.sh`) have been removed as they are no longer needed. The repository now uses `.mcp.json` for all MCP server configurations. + ## Overview This document summarizes the migration from the old `install-ai-tools.sh` MCP approach to the new `.mcp.json` approach, based on the [Anthropic MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp). +**Status**: ✅ Migration Complete - Repository now uses `.mcp.json` for MCP configuration. + ## What We've Created ### 1. Core Configuration Files diff --git a/docs/claude-to-gemini-mcp-migration.md b/docs/mcp/claude-to-gemini-mcp-migration.md similarity index 100% rename from docs/claude-to-gemini-mcp-migration.md rename to docs/mcp/claude-to-gemini-mcp-migration.md diff --git a/docs/github-mcp-setup.md b/docs/mcp/github-mcp-setup.md similarity index 100% rename from docs/github-mcp-setup.md rename to docs/mcp/github-mcp-setup.md diff --git a/docs/mcp-server-status.md b/docs/mcp/mcp-server-status.md similarity index 100% rename from docs/mcp-server-status.md rename to docs/mcp/mcp-server-status.md diff --git a/docs/memorybank-mcp-setup.md b/docs/mcp/memorybank-mcp-setup.md similarity index 100% rename from docs/memorybank-mcp-setup.md rename to docs/mcp/memorybank-mcp-setup.md diff --git a/docs/context7-setup.md b/docs/setup/context7-setup.md similarity index 100% rename from docs/context7-setup.md rename to docs/setup/context7-setup.md diff --git a/docs/qwen-setup.md b/docs/setup/qwen-setup.md similarity index 100% rename from docs/qwen-setup.md rename to docs/setup/qwen-setup.md diff --git a/docs/serena-setup.md b/docs/setup/serena-setup.md similarity index 100% rename from docs/serena-setup.md rename to docs/setup/serena-setup.md