Algolio readability fix and document refinement

codeflash/cli_cmds/cmd_init.py

@@ -7,7 +7,7 @@
 import sys
 from enum import Enum, auto
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Union, cast
+from typing import TYPE_CHECKING, Any, cast
 
 import click
 import git
@@ -50,7 +50,7 @@
 class SetupInfo:
     module_root: str
     tests_root: str
-    benchmarks_root: Union[str, None]
+    benchmarks_root: str | None
     test_framework: str
     ignore_paths: list[str]
     formatter: str
@@ -750,7 +750,7 @@ def install_github_app() -> None:
 
     else:
         click.prompt(
-            f"Finally, you'll need install the Codeflash GitHub app by choosing the repository you want to install Codeflash on.{LF}"
+            f"Finally, you'll need to install the Codeflash GitHub app by choosing the repository you want to install Codeflash on.{LF}"
             f"I will attempt to open the github app page - https://github.com/apps/codeflash-ai/installations/select_target {LF}"
             f"Press Enter to open the page to let you install the app…{LF}",
             default="",

docs/docs/getting-started/local-installation.md

@@ -8,6 +8,26 @@ Codeflash is installed and configured on a per-project basis.
 
 You can install Codeflash locally for a project by running the following command in the project's virtual environment:
 
+### Prerequisites
+
+Before installing Codeflash, ensure you have:
+
+1. **Python 3.8 or higher** installed
+2. **A Python project** with a virtual environment
+3. **Project dependencies installed** in your virtual environment
+4. **Tests** (optional) for your code (Codeflash uses tests to verify optimizations)
+
+:::important[Virtual Environment Required]
+Always install Codeflash in your project's virtual environment, not globally. Make sure your virtual environment is activated before proceeding.
+
+```bash
+# Example: Activate your virtual environment
+source venv/bin/activate  # On Linux/Mac
+# or
+venv\Scripts\activate     # On Windows
+```
+:::
+### Step 1: Install Codeflash
 ```bash
 pip install codeflash
 ```
@@ -16,22 +36,39 @@ pip install codeflash
 We recommend installing Codeflash as a development dependency.
 It doesn't need to be installed as part of your package requirements. 
 Codeflash is intended to be used locally and as part of development workflows such as CI.
+If using pyproject.toml:
+```toml
+[tool.poetry.dependencies.dev]
+codeflash = "^latest"
+```
+Or with pip:
+```bash
+pip install --dev codeflash
+````
 :::
 
-## Generate a Codeflash API Key
+### Step 2: Generate a Codeflash API Key
 
-Since Codeflash uses advanced Large Language Models (LLMs) that are hosted in the cloud, you will need to generate an API key to use Codeflash.
+Codeflash uses cloud-hosted AI models to optimize your code. You'll need an API key to use it.
 
-To generate an API key, visit the [Codeflash Web App](https://app.codeflash.ai/) and sign up for an account with GitHub login.
+1. Visit the [Codeflash Web App](https://app.codeflash.ai/) 
+2. Sign up with your GitHub account (free)
+3. Navigate to the [API Key](https://app.codeflash.ai/app/apikeys) page to generate your API key
 <!--- TODO: Do we ask for access to specific repositories here? --->
-Once you have signed up, you will be able to generate an API key from the [API Key](https://app.codeflash.ai/app/apikeys) page.
-You will need the API key in the next step.
 
-## Automatic Configuration
+:::note[Free Tier Available]
+Codeflash offers a **free tier** with a limited number of optimizations per month. Perfect for trying it out or small projects!
+:::
+
+### Step 3: Automatic Configuration
 
-To configure Codeflash for a project, in the root directory of your project where your `pyproject.toml` file is located, run the following command :
+Navigate to your project's root directory (where your `pyproject.toml` file is or should be) and run:
 
 ```bash
+# Make sure you're in your project root
+cd /path/to/your/project
+
+# Run the initialization
 codeflash init
 ```
 
@@ -56,11 +93,90 @@ After you have answered these questions, Codeflash will be configured for your p
 The configuration will be saved in the `pyproject.toml` file in the root directory of your project.
 To understand the configuration options, and set more advanced options, see the [Configuration](/configuration) page.
 
-## Install the Codeflash GitHub App
+### Step 4: Install the Codeflash GitHub App
 
+<!--- TODO: Justify to users Why we need the user to install Github App even in local Installation or local optimization? --->
 Finally, if you have not done so already, Codeflash will ask you to install the Github App in your repository.  The Codeflash GitHub App allows access to your repository to the codeflash-ai bot to open PRs, review code, and provide optimization suggestions.
 
 Please [install the Codeflash GitHub
 app](https://github.com/apps/codeflash-ai/installations/select_target) by choosing the repository you want to install
 Codeflash on.
 ## 
+
+## Try It Out!
+
+Once configured, you can start optimizing your code:
+
+```bash
+# Optimize a specific function
+codeflash --file path/to/your/file.py --function function_name
+
+# Or if want to optimize only locally without creating a PR
+codeflash --file path/to/your/file.py --function function_name --no-pr
+```
+
+### Example Project
+
+Want to see Codeflash in action? Check out our example repository:
+
+🔗 [github.com/codeflash-ai/optimize-me](https://github.com/codeflash-ai/optimize-me)
+
+This repo includes:
+- Sample Python code with performance issues
+- Tests for verification
+- Pre-configured `pyproject.toml`
+- Before/after optimization examples in PRs
+
+Clone it and try running:
+```bash
+git clone https://github.com/codeflash-ai/optimize-me.git
+cd optimize-me
+python -m venv .venv
+source .venv/bin/activate  # or venv\Scripts\activate on Windows
+pip install -r requirements.txt
+pip install codeflash
+codeflash init  # Use your own API key
+codeflash --all # optimize the entire repo
+```
+
+### 🔧 Troubleshooting
+
+#### 📦 "Module not found" errors
+Make sure:
+- ✅ Your virtual environment is activated
+- ✅ All project dependencies are installed
+- ✅ You're running `codeflash` from your project root
+
+#### 🧪 "No optimizations found" or debugging issues
+Use the `--verbose` flag for detailed output:
+```bash
+codeflash optimize --verbose
+```
+
+This will show:
+- 🔍 Which functions are being analyzed
+- 🚫 Why certain functions were skipped
+- ⚠️ Detailed error messages
+- 📊 Performance analysis results
+
+#### 🔍 "No tests found" errors
+Verify:
+- 📁 Your test directory path is correct in `pyproject.toml`
+- 🔍 Tests are discoverable by your test framework
+- 📝 Test files follow naming conventions (`test_*.py` for pytest)
+
+#### ⚙️ Configuration issues
+Check your `pyproject.toml`:
+```toml
+[tool.codeflash]
+module = "my_package"
+test-framework = "pytest"
+tests = "tests/"
+```
+
+### Next Steps
+
+- Learn about [Codeflash Concepts](/codeflash-concepts/how-codeflash-works)
+- Explore [optimization workflows](/optimizing-with-codeflash/one-function)
+- Set up [GitHub Actions integration](/getting-started/codeflash-github-actions)
+- Read [configuration options](/configuration) for advanced setups

docs/src/css/custom.css

@@ -28,3 +28,8 @@
   --ifm-color-primary-lightest: #FFECB3;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
 }
+
+[data-theme='dark'] {
+  /* Attempt to override Algolia's own CSS variables for the selected item's background */
+  --docsearch-highlight-color: #d08e0d !important;
+}