Add mdBook documentation with Ghostty-style sidebar

2025-12-01 15:12:50 -08:00
parent 012e22ea6f
commit ef7d4cccc1
38 changed files with 4886 additions and 12 deletions
@@ -0,0 +1,345 @@
+# Contributing to socktop Documentation
+
+Thank you for your interest in improving the socktop documentation!
+
+## Quick Start
+
+1. **Install documentation tools:**
+   ```bash
+   ./setup-docs.sh
+   ```
+
+2. **Make your changes** to the relevant `.md` files in `src/`
+
+3. **Test locally:**
+   ```bash
+   mdbook serve
+   ```
+   Open http://localhost:3000 to preview
+
+4. **Submit a pull request** with your changes
+
+## Documentation Structure
+
+```
+docs/src/
+├── SUMMARY.md              # Table of contents (edit when adding pages)
+├── introduction.md         # Project overview
+├── installation/           # Installation guides
+├── usage/                  # Usage documentation
+├── security/              # Security guides
+└── advanced/              # Advanced topics
+```
+
+## Writing Guidelines
+
+### Style Guide
+
+- **Be clear and concise** - Users want answers, not prose
+- **Use active voice** - "Run the command" not "The command should be run"
+- **Include examples** - Show, don't just tell
+- **Test your code** - Verify all commands and code examples work
+- **Link related content** - Help users discover related topics
+
+### Markdown Formatting
+
+Use standard Markdown with these conventions:
+
+#### Code Blocks
+
+Always specify the language:
+
+~~~markdown
+```bash
+cargo install socktop
+```
+
+```rust
+use socktop_connector::*;
+```
+
+```toml
+[profiles.server]
+url = "ws://localhost:3000"
+```
+~~~
+
+#### Command Examples
+
+Show both the command and expected output:
+
+```bash
+# Check version
+socktop --version
+# Output: socktop 1.50.2
+```
+
+#### Admonitions
+
+Use clear callouts for important information:
+
+```markdown
+**Note:** This requires root permissions.
+
+**Warning:** This will delete all data.
+
+**Tip:** Use Ctrl+C to exit.
+```
+
+#### Links
+
+Use descriptive link text:
+
+```markdown
+✅ Good: See [Agent Service Setup](../installation/agent-service.md)
+❌ Bad:  Click [here](../installation/agent-service.md)
+```
+
+### Page Structure
+
+Each page should follow this template:
+
+```markdown
+# Page Title
+
+Brief introduction explaining what this page covers.
+
+## Section 1
+
+Content...
+
+### Subsection 1.1
+
+More specific content...
+
+## Section 2
+
+More content...
+
+## Next Steps
+
+- [Related Topic 1](./related-topic-1.md)
+- [Related Topic 2](./related-topic-2.md)
+
+<!-- TODO: Add more documentation -->
+<!-- TODO: Add specific improvements needed -->
+```
+
+## Adding New Pages
+
+1. **Create the file** in the appropriate directory:
+   ```bash
+   touch src/installation/new-guide.md
+   ```
+
+2. **Add to SUMMARY.md** in the correct section:
+   ```markdown
+   # Installation
+   
+   - [Quick Start](./installation/quick-start.md)
+   - [New Guide](./installation/new-guide.md)  # Add here
+   ```
+
+3. **Write the content** following the guidelines above
+
+4. **Test the build:**
+   ```bash
+   mdbook build
+   mdbook serve
+   ```
+
+5. **Check for broken links:**
+   - Navigate to your new page
+   - Click all internal links
+   - Verify they work correctly
+
+## Updating Existing Pages
+
+1. **Edit the `.md` file** directly
+
+2. **Maintain consistency:**
+   - Keep the same writing style
+   - Don't remove useful examples
+   - Update version numbers if needed
+
+3. **Update related pages** if your changes affect them
+
+4. **Test thoroughly:**
+   ```bash
+   mdbook serve
+   ```
+
+## TODO Comments
+
+Use TODO comments to mark areas needing work:
+
+```markdown
+<!-- TODO: Add more documentation -->
+<!-- TODO: Add screenshots -->
+<!-- TODO: Add video demonstration -->
+<!-- TODO: Expand with more examples -->
+```
+
+These help identify areas for future improvement.
+
+## Screenshots and Images
+
+When adding images:
+
+1. **Create an `images/` directory** in the relevant section:
+   ```bash
+   mkdir -p src/installation/images
+   ```
+
+2. **Use descriptive filenames:**
+   ```
+   ✅ Good: installation-apt-repository.png
+   ❌ Bad:  screenshot1.png
+   ```
+
+3. **Reference in Markdown:**
+   ```markdown
+   ![APT Repository Setup](./images/installation-apt-repository.png)
+   ```
+
+4. **Optimize images:**
+   - Use PNG for screenshots
+   - Use JPG for photos
+   - Compress to reduce file size
+   - Maximum width: 1200px
+
+## Code Examples
+
+### Shell Scripts
+
+```bash
+#!/bin/bash
+# Always include a description comment
+
+# Use descriptive variable names
+SERVER_URL="ws://localhost:3000"
+
+# Show error handling
+if ! command -v socktop &> /dev/null; then
+    echo "Error: socktop not installed"
+    exit 1
+fi
+
+# Clear, commented steps
+socktop "$SERVER_URL"
+```
+
+### Rust Code
+
+```rust
+// Include necessary imports
+use socktop_connector::*;
+
+// Add comments for complex logic
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Connect to agent
+    let mut connector = connect_to_socktop_agent("ws://localhost:3000/ws").await?;
+    
+    // Request metrics
+    match connector.request(AgentRequest::Metrics).await {
+        Ok(AgentResponse::Metrics(m)) => {
+            println!("CPU: {:.1}%", m.cpu_total);
+        }
+        Err(e) => eprintln!("Error: {}", e),
+        _ => unreachable!(),
+    }
+    
+    Ok(())
+}
+```
+
+### Configuration Files
+
+Always show complete, working examples:
+
+```toml
+# ~/.config/socktop/profiles.toml
+
+[profiles.production]
+url = "wss://prod.example.com:3000"
+token = "your-token-here"
+ca_cert = "/etc/ssl/certs/ca.pem"
+verify_tls = true
+```
+
+## Testing Your Changes
+
+### Local Preview
+
+```bash
+# Start development server
+mdbook serve
+
+# Open in browser
+# Navigate to your changed pages
+# Verify formatting and links
+```
+
+### Build Test
+
+```bash
+# Clean build
+rm -rf book/
+mdbook build
+
+# Check for warnings
+# Fix any broken links or errors
+```
+
+### Cross-Reference Check
+
+- Click all internal links
+- Verify they point to correct pages
+- Check that anchor links work
+- Test external links
+
+## Submitting Changes
+
+1. **Commit with clear messages:**
+   ```bash
+   git add docs/src/installation/new-guide.md
+   git commit -m "docs: Add new installation guide for Docker"
+   ```
+
+2. **Push to your fork:**
+   ```bash
+   git push origin docs/docker-install
+   ```
+
+3. **Create pull request:**
+   - Describe what you added/changed
+   - Explain why it's needed
+   - Link to any related issues
+
+## Documentation Priorities
+
+Focus on these high-impact areas:
+
+1. **Missing content** marked with TODO comments
+2. **User-reported confusion** from issues/discussions
+3. **New features** that need documentation
+4. **Common questions** that arise frequently
+5. **Error scenarios** and troubleshooting
+
+## Getting Help
+
+- **Questions?** Open a discussion on GitHub
+- **Found a bug in docs?** Open an issue with the "documentation" label
+- **Want to discuss major changes?** Start with an issue before writing
+
+## Recognition
+
+All documentation contributors will be acknowledged in:
+- Git history
+- Contributors list
+- Release notes (for significant contributions)
+
+## Thank You!
+
+Good documentation is crucial for project success. Your contributions help users get started faster and use socktop more effectively. Thank you for helping improve the documentation! 🎉