diff --git a/docs/cli-reference/flags.mdx b/docs/cli-reference/flags.mdx deleted file mode 100644 index ad9fc5f31..000000000 --- a/docs/cli-reference/flags.mdx +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: "Flags Reference" -description: "Complete reference for all Codeflash CLI flags and options" -icon: "list" -sidebarTitle: "Flags Reference" -keywords: ["flags", "options", "arguments", "command line"] ---- - -# Flags Reference - -Complete reference for all Codeflash CLI flags and command-line options. - ---- - -## Main Command Flags - -| Flag | Type | Description | -|------|------|-------------| -| `--file` | `PATH` | Optimize only this file | -| `--function` | `NAME` | Optimize only this function (requires `--file`) | -| `--all` | `[PATH]` | Optimize all functions. Optional path to start from | -| `--replay-test` | `PATH` | Path to replay test file(s) | -| `--benchmark` | flag | Enable benchmark mode | -| `--no-pr` | flag | Don't create PR, update locally | -| `--no-gen-tests` | flag | Don't generate tests | -| `--no-draft` | flag | Skip draft PRs | -| `--worktree` | flag | Use git worktree | -| `--staging-review` | flag | Upload to staging | -| `--verbose` / `-v` | flag | Verbose debug output | -| `--verify-setup` | flag | Run setup verification | -| `--version` | flag | Show version | - ---- - -## Configuration Override Flags - -Override settings from `pyproject.toml` via command line. - -| Flag | Type | Description | -|------|------|-------------| -| `--config-file` | `PATH` | Path to pyproject.toml | -| `--module-root` | `PATH` | Python module root directory | -| `--tests-root` | `PATH` | Tests directory | -| `--benchmarks-root` | `PATH` | Benchmarks directory | - - - - - ```bash - # Override config file location - codeflash --file src/app.py --function main --config-file configs/pyproject.toml --no-pr - - # Override module root - codeflash --file src/app.py --function main --module-root src --no-pr - - # Override tests root - codeflash --file src/app.py --function main --tests-root tests/unit --no-pr - - # Combine multiple overrides - codeflash --file src/app.py --function main \ - --module-root src \ - --tests-root tests \ - --no-pr - ``` - - - ```powershell - # Override config file location - codeflash --file src\app.py --function main --config-file configs\pyproject.toml --no-pr - - # Override module root - codeflash --file src\app.py --function main --module-root src --no-pr - - # Override tests root - codeflash --file src\app.py --function main --tests-root tests\unit --no-pr - ``` - - - - ---- - -## Optimize Subcommand Flags - -Flags specific to the `codeflash optimize` command. - -| Flag | Type | Description | -|------|------|-------------| -| `--output` | `PATH` | Trace file output path (default: `codeflash.trace`) | -| `--timeout` | `INT` | Maximum trace time in seconds | -| `--max-function-count` | `INT` | Max times to trace a function (default: 100) | -| `--config-file-path` | `PATH` | Path to pyproject.toml | -| `--trace-only` | flag | Only trace, don't optimize | - - - The `--output` flag specifies where to save the trace file. If not specified, it defaults to `codeflash.trace` in the current directory. - - ---- - -## Behavior Flags - -Control how Codeflash behaves during optimization. - -| Flag | Description | -|------|-------------| -| `--no-pr` | Run locally without creating a pull request | -| `--no-gen-tests` | Use only existing tests, skip test generation | -| `--no-draft` | Skip optimization for draft PRs (CI mode) | -| `--worktree` | Use git worktree for isolated optimization | -| `--staging-review` | Upload optimizations to staging for review | -| `--verbose` / `-v` | Enable verbose debug logging | - - -```bash -# Local optimization only -codeflash --file src/app.py --function main --no-pr - -# Use only existing tests -codeflash --file src/app.py --function main --no-gen-tests --no-pr - -# Enable verbose logging -codeflash --file src/app.py --function main --verbose --no-pr - -# Use worktree for isolation -codeflash --file src/app.py --function main --worktree --no-pr - -# Upload to staging -codeflash --all --staging-review --no-pr -``` - - ---- - -## Flag Combinations - -Common flag combinations for different use cases: - -### Local Development - -```bash -# Optimize locally with verbose output -codeflash --file src/app.py --function main --no-pr --verbose -``` - -### CI/CD Pipeline - -```bash -# Skip draft PRs and use existing tests only -codeflash --all --no-draft --no-gen-tests -``` - -### Debugging - -```bash -# Trace only with custom output and timeout -codeflash optimize app.py --trace-only --output debug.trace --timeout 60 -``` - -### Custom Configuration - -```bash -# Override multiple config settings -codeflash --file src/app.py --function main \ - --module-root src \ - --tests-root tests/unit \ - --benchmarks-root tests/benchmarks \ - --no-pr -``` - ---- - -## Next Steps - - - - Learn how to use optimization commands - - - Fix common issues - - - diff --git a/docs/cli-reference/index.mdx b/docs/cli-reference/index.mdx deleted file mode 100644 index f91fb2e1b..000000000 --- a/docs/cli-reference/index.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: "CLI Reference" -description: "Complete command-line reference for Codeflash CLI commands, flags, and options" -icon: "terminal" -sidebarTitle: "Overview" -keywords: - [ - "CLI", - "command line", - "commands", - "flags", - "options", - "reference", - "terminal", - ] ---- - -# Codeflash CLI Reference - -Complete command-line reference for all Codeflash commands, flags, and options with practical examples you can run directly in your terminal. - - - **Prerequisites** - Ensure Codeflash is installed in your Python environment - and you have a configured `pyproject.toml` in your project. - - ---- - -## Quick Start - - - - ```bash - # Activate virtual environment (if using one) - source .venv/bin/activate - - # Verify installation - codeflash --version - ``` - - - ```powershell - # Activate virtual environment (if using one) - .venv\Scripts\activate - - # Verify installation - codeflash --version - ``` - - - ---- - -## Common Workflows - -### 1. First-Time Setup - - - - ```bash - pip install codeflash - ``` - - - ```bash - codeflash init - ``` - - - ```bash - codeflash --verify-setup - ``` - - - ```bash - codeflash --file src/main.py --function my_function --no-pr - ``` - - - ---- - -### 2. Optimize a Workflow - - - - ```bash - codeflash optimize my_script.py --arg1 value1 - ``` - - - Check the generated PR or local changes for optimization suggestions. - - - ---- - -### 3. CI/CD Integration - - - - ```bash - codeflash init-actions - ``` - - - Review and merge the generated GitHub Actions workflow. - - - Codeflash will now optimize code in every PR automatically! - - - ---- - -## Help & Version - -```bash -# Display version -codeflash --version - -# Main help -codeflash --help - -# Subcommand help -codeflash optimize --help -codeflash init --help -``` - ---- - -## Documentation Structure - -This CLI reference is organized into the following sections: - - - - Initialize projects, set up GitHub Actions, and verify installation - - - Optimize single functions or entire codebases - - - Trace script execution and optimize based on real usage - - - Complete reference for all command-line flags - - - Solutions for common CLI issues - - - ---- - -## Next Steps - - - - Learn how to optimize individual functions - - - Optimize entire workflows with tracing - - - Set up continuous optimization - - - Advanced configuration options - - - diff --git a/docs/cli-reference/optimization.mdx b/docs/cli-reference/optimization.mdx deleted file mode 100644 index 34284e4b0..000000000 --- a/docs/cli-reference/optimization.mdx +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: "Optimization Commands" -description: "Optimize single functions or entire codebases with Codeflash CLI" -icon: "bullseye" -sidebarTitle: "Optimization Commands" -keywords: ["optimization", "function", "file", "all", "commands"] ---- - -# Optimization Commands - -Commands for optimizing individual functions or entire codebases. - ---- - -## Optimize a Single Function - -Target a specific function in a file for optimization. - -```bash -codeflash --file --function -``` - - - - - ```bash - # Basic optimization (creates PR) - codeflash --file src/utils.py --function calculate_metrics - - # Local optimization only (no PR) - codeflash --file src/utils.py --function calculate_metrics --no-pr - - # With verbose output - codeflash --file src/utils.py --function calculate_metrics --no-pr --verbose - ``` - - - ```powershell - # Basic optimization (creates PR) - codeflash --file src\utils.py --function calculate_metrics - - # Local optimization only (no PR) - codeflash --file src\utils.py --function calculate_metrics --no-pr - - # With verbose output - codeflash --file src\utils.py --function calculate_metrics --no-pr --verbose - ``` - - - - - - **Important**: The file must be within your configured `module-root` - directory. Files outside `module-root` will be ignored with "Functions outside - module-root" message. - - ---- - -## Optimize All Functions - -Optimize all functions in your entire codebase or a specific directory. - -```bash -# Optimize entire codebase -codeflash --all - -# Optimize specific directory -codeflash --all src/core/ -``` - - - - - ```bash - # Optimize all (creates PRs) - codeflash --all - - # Optimize all locally (no PRs) - codeflash --all --no-pr - - # Optimize specific directory - codeflash --all src/algorithms/ --no-pr - - # Skip draft PRs in CI - codeflash --all --no-draft - ``` - - - ```powershell - # Optimize all (creates PRs) - codeflash --all - - # Optimize all locally (no PRs) - codeflash --all --no-pr - - # Optimize specific directory - codeflash --all src\algorithms\ --no-pr - - # Skip draft PRs in CI - codeflash --all --no-draft - ``` - - - - - - When using `--all`, Codeflash will: - - Discover all optimizable functions in your codebase - - Create separate PRs for each function (or update locally with `--no-pr`) - - Process functions in batches to avoid overwhelming your repository - - ---- - -## Benchmark Mode - -Optimize code based on performance benchmarks using pytest-benchmark format. - -```bash -codeflash --file --benchmark --benchmarks-root -``` - - - - - ```bash - # With benchmarks-root flag - codeflash --file src/core.py --benchmark --benchmarks-root tests/benchmarks --no-pr - - # If benchmarks-root is in pyproject.toml - codeflash --file src/core.py --benchmark --no-pr - ``` - - - ```powershell - # With benchmarks-root flag - codeflash --file src\core.py --benchmark --benchmarks-root tests\benchmarks --no-pr - - # If benchmarks-root is in pyproject.toml - codeflash --file src\core.py --benchmark --no-pr - ``` - - - - - - The `--benchmarks-root` directory must exist and be configured either via - `pyproject.toml` or the command-line flag. - - ---- - -## Next Steps - - - - Learn about trace-based optimization - - - Complete flag reference - - - diff --git a/docs/cli-reference/setup.mdx b/docs/cli-reference/setup.mdx deleted file mode 100644 index c9a3be441..000000000 --- a/docs/cli-reference/setup.mdx +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: "Setup Commands" -description: "Initialize projects, set up GitHub Actions, and verify Codeflash installation" -icon: "wrench" -sidebarTitle: "Setup Commands" -keywords: ["setup", "init", "installation", "github actions", "verify"] ---- - -# Setup Commands - -Commands for initializing Codeflash in your project, setting up continuous optimization, and verifying your installation. - ---- - -## `codeflash init` - -Initialize Codeflash for your Python project. This creates the configuration in `pyproject.toml`. - - -```bash Basic -codeflash init -``` - -```bash With Formatter Override -codeflash init --override-formatter-check -``` - - - - The `init` command will guide you through an interactive setup process, - including API key configuration, module selection, and GitHub App - installation. - - -**What it does:** - -- Prompts for your Python module directory (`module-root`) -- Prompts for your test directory (`tests-root`) -- Configures code formatter preferences -- Sets up telemetry preferences -- Optionally installs the Codeflash VS Code extension -- Optionally sets up GitHub Actions workflow - ---- - -## `codeflash init-actions` - -Set up GitHub Actions workflow for continuous optimization on every pull request. - -```bash -codeflash init-actions -``` - -**What it does:** - -- Creates a workflow file in `.github/workflows/` -- Opens a PR with the workflow configuration -- Requires the Codeflash GitHub App to be installed - - - This command requires the Codeflash GitHub App to be installed on your repository. If you haven't installed it, you'll be prompted with a link to do so. - - ---- - -## `codeflash vscode-install` - -Install the Codeflash extension for VS Code, Cursor, or Windsurf. - -```bash -codeflash vscode-install -``` - -**What it does:** - -- Detects which editor you're using (VS Code, Cursor, or Windsurf) -- Downloads and installs the appropriate extension -- Works with both Marketplace and Open VSX sources - - - This command is also run automatically during `codeflash init` if you choose to install the extension. - - ---- - -## `codeflash --verify-setup` - -Verify your Codeflash installation by running a sample optimization. - -```bash -codeflash --verify-setup -``` - -**What it does:** - -- Creates a temporary demo file -- Runs a sample optimization -- Verifies all components are working correctly -- Cleans up the demo file afterward - - - This command takes about 3 minutes to complete. It's a great way to ensure everything is set up correctly before optimizing your actual code. - - ---- - -## Next Steps - - - - Learn how to optimize functions - - - Complete flag reference - - - diff --git a/docs/cli-reference/tracing.mdx b/docs/cli-reference/tracing.mdx deleted file mode 100644 index c2394a6d5..000000000 --- a/docs/cli-reference/tracing.mdx +++ /dev/null @@ -1,213 +0,0 @@ ---- -title: "Tracing & Workflows" -description: "Trace script execution and optimize functions based on real-world usage" -icon: "route" -sidebarTitle: "Tracing & Workflows" -keywords: ["tracing", "optimize", "workflow", "replay test", "pytest"] ---- - -# Tracing & Workflows - -Trace Python script execution and optimize functions based on real-world usage patterns. - ---- - -## `codeflash optimize` - -Trace a Python script's execution and optimize functions based on real-world usage. - -```bash -codeflash optimize [script_args] -``` - - - - - ```bash - # Basic trace and optimize - codeflash optimize app.py - - # With script arguments - codeflash optimize process.py --input data.csv --output results.json - - # Custom trace output file - codeflash optimize app.py --output custom_trace.trace - - # With timeout (30 seconds) - codeflash optimize long_running_script.py --timeout 30 - - # Limit function trace count - codeflash optimize app.py --max-function-count 50 - - # Specify config file - codeflash optimize app.py --config-file-path pyproject.toml - - # Local only (no PR) - codeflash optimize app.py --no-pr - ``` - - - ```powershell - # Basic trace and optimize - codeflash optimize app.py - - # With script arguments - codeflash optimize process.py --input data.csv --output results.json - - # Custom trace output file - codeflash optimize app.py --output custom_trace.trace - - # With timeout (30 seconds) - codeflash optimize long_running_script.py --timeout 30 - - # Limit function trace count - codeflash optimize app.py --max-function-count 50 - - # Specify config file - codeflash optimize app.py --config-file-path pyproject.toml - - # Local only (no PR) - codeflash optimize app.py --no-pr - ``` - - - - -**How it works:** - -1. Runs your script with the provided arguments -2. Traces all function calls during execution -3. Identifies which functions are called and how often -4. Generates replay tests based on actual usage -5. Optimizes the traced functions - ---- - -## Trace with pytest - -Optimize functions called during pytest test execution. - - - - ```bash - # Trace pytest tests - codeflash optimize -m pytest tests/ - - # Trace specific test file - codeflash optimize -m pytest tests/test_core.py - - # With pytest arguments - codeflash optimize -m pytest tests/ -v --tb=short - ``` - - - ```powershell - # Trace pytest tests - codeflash optimize -m pytest tests\ - - # Trace specific test file - codeflash optimize -m pytest tests\test_core.py - - # With pytest arguments - codeflash optimize -m pytest tests\ -v --tb=short - ``` - - - - - Tracing pytest tests is great for optimizing functions that are heavily used in your test suite, ensuring optimizations work correctly with your existing tests. - - ---- - -## Trace Only (Generate Replay Tests) - -Create trace files and replay tests without running optimization. - - - - ```bash - # Trace only - generates replay test - codeflash optimize app.py --output trace_file.trace --trace-only - - # Then optimize using the replay test - codeflash --replay-test tests/test_app_py__replay_test_0.py --no-pr - ``` - - - ```powershell - # Trace only - generates replay test - codeflash optimize app.py --output trace_file.trace --trace-only - - # Then optimize using the replay test - codeflash --replay-test tests\test_app_py__replay_test_0.py --no-pr - ``` - - - - - **Replay test naming**: Files are named based on the traced script path. For - `src/app.py`, the replay test will be named like - `test_srcapp_py__replay_test_0.py`. - - -**Use cases for trace-only:** - -- Generate replay tests for later optimization -- Debug tracing issues without running full optimization -- Create reusable test cases from script execution - ---- - -## Replay Test Optimization - -Optimize functions using previously generated replay tests. - -```bash -codeflash --replay-test -``` - - - - - ```bash - # Optimize using replay test - codeflash --replay-test tests/test_app_py__replay_test_0.py --no-pr - - # Multiple replay tests - codeflash --replay-test tests/test_*.py --no-pr - ``` - - - ```powershell - # Optimize using replay test - codeflash --replay-test tests\test_app_py__replay_test_0.py --no-pr - - # Multiple replay tests (use Get-ChildItem for globbing) - codeflash --replay-test (Get-ChildItem tests\test_*.py) --no-pr - ``` - - - - ---- - -## Next Steps - - - - Learn about function optimization - - - Complete flag reference - - - diff --git a/docs/cli-reference/troubleshooting.mdx b/docs/cli-reference/troubleshooting.mdx deleted file mode 100644 index 7c8134242..000000000 --- a/docs/cli-reference/troubleshooting.mdx +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: "CLI Troubleshooting" -description: "Solutions for common Codeflash CLI issues and errors" -icon: "wrench" -sidebarTitle: "Troubleshooting" -keywords: ["troubleshooting", "errors", "issues", "problems", "debugging"] ---- - -# CLI Troubleshooting - -Solutions for common issues when using the Codeflash CLI. - ---- - -## Common Issues - - - - **Problem**: Function not found because file is outside `module-root`. - - **Solution**: Ensure your file is within the `module-root` directory specified in `pyproject.toml`. - - ```bash - # Check your module-root - grep "module-root" pyproject.toml - - # Use the correct path (e.g., if module-root is "src") - codeflash --file src/myfile.py --function my_function --no-pr - ``` - - - - **Problem**: Using `--benchmark` without specifying benchmarks directory. - - **Solution**: Either add `benchmarks-root` to `pyproject.toml` or use the flag: - - ```bash - codeflash --file src/app.py --benchmark --benchmarks-root tests/benchmarks --no-pr - ``` - - - - **Problem**: Replay test filename doesn't match expected path. - - **Solution**: Replay tests include the module path in their name. Check the actual filename: - - ```bash - # Linux/macOS - ls tests/test_*replay*.py - - # Windows - dir tests\test_*replay*.py - ``` - - - Replay test files are named based on the traced script path. For `src/app.py`, - the replay test will be named like `test_srcapp_py__replay_test_0.py`. - - - - - **Problem**: PR creation fails due to missing GitHub App. - - **Solution**: Install the Codeflash GitHub App or use `--no-pr` for local optimization: - - ```bash - # Local optimization - codeflash --file src/app.py --function main --no-pr - - # Or install the GitHub App - # https://github.com/apps/codeflash-ai/installations/select_target - ``` - - - - **Problem**: Codeflash can't find your Python modules. - - **Solution**: - - 1. Verify `module-root` is correctly set in `pyproject.toml` - 2. Ensure you're running from the project root - 3. Check that your Python environment has all dependencies installed - - ```bash - # Verify module-root - cat pyproject.toml | grep module-root - - # Check Python path - python -c "import sys; print(sys.path)" - ``` - - - - **Problem**: Codeflash can't generate tests for your function. - - **Solution**: - - 1. Ensure your function has a return statement - 2. Check that the function is not a property or class method with special decorators - 3. Use `--no-gen-tests` to skip test generation and use existing tests only - - ```bash - codeflash --file src/app.py --function main --no-gen-tests --no-pr - ``` - - - - **Problem**: Optimization takes too long or times out. - - **Solution**: - - 1. Use `--verbose` to see what's happening - 2. For tracing, use `--timeout` to limit trace duration - 3. For large functions, consider breaking them down - - ```bash - # Limit trace time - codeflash optimize app.py --timeout 30 - - # See detailed progress - codeflash --file src/app.py --function main --verbose --no-pr - ``` - - - ---- - -## Getting Help - -If you're still experiencing issues: - -1. **Check the logs**: Use `--verbose` flag to see detailed output -2. **Verify setup**: Run `codeflash --verify-setup` to check your installation -3. **Check configuration**: Ensure `pyproject.toml` is correctly configured -4. **View help**: Run `codeflash --help` or `codeflash --help` - ---- - -## Next Steps - - - - Review setup and initialization - - - Complete flag reference - - - diff --git a/docs/docs.json b/docs/docs.json index a36fc82dc..df5098d34 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -18,33 +18,13 @@ { "tab": "Documentation", "groups": [ - { - "group": "🚀 Quickstart", - "pages": ["getting-started/local-installation"] - }, { "group": "🏠 Overview", "pages": ["index"] }, { - "group": "📖 Codeflash CLI", - "pages": [ - "cli-reference/index", - "cli-reference/setup", - "cli-reference/optimization", - "cli-reference/tracing", - "cli-reference/flags", - "cli-reference/troubleshooting" - ] - }, - { - "group": "🛠 IDE Extension", - "pages": [ - "editor-plugins/vscode/index", - "editor-plugins/vscode/features", - "editor-plugins/vscode/configuration", - "editor-plugins/vscode/troubleshooting" - ] + "group": "🚀 Quickstart", + "pages": ["getting-started/local-installation"] }, { "group": "⚡ Optimizing with Codeflash", @@ -62,6 +42,15 @@ "optimizing-with-codeflash/review-optimizations" ] }, + { + "group": "🛠 IDE Extension", + "pages": [ + "editor-plugins/vscode/index", + "editor-plugins/vscode/features", + "editor-plugins/vscode/configuration", + "editor-plugins/vscode/troubleshooting" + ] + }, { "group": "🧠 Core Concepts", "pages": [ diff --git a/docs/editor-plugins/vscode/configuration.mdx b/docs/editor-plugins/vscode/configuration.mdx index a19400d37..d8a113a2d 100644 --- a/docs/editor-plugins/vscode/configuration.mdx +++ b/docs/editor-plugins/vscode/configuration.mdx @@ -146,7 +146,4 @@ When configuration issues are detected, the extension displays clear error messa Complete pyproject.toml reference - - Command-line options - diff --git a/docs/editor-plugins/vscode/index.mdx b/docs/editor-plugins/vscode/index.mdx index f598fe594..8cf0f3b10 100644 --- a/docs/editor-plugins/vscode/index.mdx +++ b/docs/editor-plugins/vscode/index.mdx @@ -204,7 +204,6 @@ The extension works alongside the Codeflash CLI. You can: - **Use extension for interactive work** — Optimize individual functions as you code - **Mix both** — The extension picks up CLI results when you return to the editor -For CLI documentation, see the [Codeflash CLI](/cli-reference/index). --- @@ -220,9 +219,6 @@ For CLI documentation, see the [Codeflash CLI](/cli-reference/index). Fix common issues - - Command-line interface docs - --- diff --git a/docs/editor-plugins/vscode/troubleshooting.mdx b/docs/editor-plugins/vscode/troubleshooting.mdx index 7af38446c..09a408ec1 100644 --- a/docs/editor-plugins/vscode/troubleshooting.mdx +++ b/docs/editor-plugins/vscode/troubleshooting.mdx @@ -208,8 +208,5 @@ If you're still experiencing issues: Customize extension settings - - Command-line interface docs -