Skip to content

Revamp and polish the docs more #671

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 20, 2025
Merged

Revamp and polish the docs more #671

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
678b55a
Revamp and polish the docs more
misrasaurabh1 Aug 20, 2025
ffb63a7
Merge branch 'main' into docs-update-1
misrasaurabh1 Aug 20, 2025
78daf09
Fix typo
misrasaurabh1 Aug 20, 2025
50dca68
Merge remote-tracking branch 'origin/docs-update-1' into docs-update-1
misrasaurabh1 Aug 20, 2025
c47f28c
updates
misrasaurabh1 Aug 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/codeflash-concepts/how-codeflash-works.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Codeflash runs tests for the target function using either pytest or unittest fra

#### Performance benchmarking

Codeflash implements [several techniques](/codeflash-concepts/benchmarking.md) to measure code performance accurately. In particular, it runs multiple iterations of the code in a loop to determine the best performance with the minimum runtime. Codeflash compares the performance of the original code against the optimization, requiring at least a 10% speed improvement before considering it to be faster. This approach eliminates most runtime measurement variability, even on noisy CI systems and virtual machines. The final runtime Codeflash reports is the minimum total time it took to run all the test cases.
Codeflash implements [several techniques](/codeflash-concepts/benchmarking) to measure code performance accurately. In particular, it runs multiple iterations of the code in a loop to determine the best performance with the minimum runtime. Codeflash compares the performance of the original code against the optimization, requiring at least a 10% speed improvement before considering it to be faster. This approach eliminates most runtime measurement variability, even on noisy CI systems and virtual machines. The final runtime Codeflash reports is the minimum total time it took to run all the test cases.

## Creating Pull Requests

Expand Down
45 changes: 18 additions & 27 deletions docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,25 +25,24 @@
]
},
{
"group": "🚀 Getting Started",
"group": "🚀 Quickstart",
"pages": [
"getting-started/local-installation"
]
},
{
"group": "🔧 Continuous Optimization",
"group": "⚡ Optimizing with Codeflash",
"pages": [
"getting-started/codeflash-github-actions",
"optimizing-with-codeflash/optimize-prs",
"optimizing-with-codeflash/benchmarking"
"optimizing-with-codeflash/one-function",
"optimizing-with-codeflash/trace-and-optimize",
"optimizing-with-codeflash/codeflash-all"
]
},
{
"group": "⚡ Optimization Workflows",
"group": "✨ Continuous Optimization",
"pages": [
"optimizing-with-codeflash/one-function",
"optimizing-with-codeflash/trace-and-optimize",
"optimizing-with-codeflash/codeflash-all"
"optimizing-with-codeflash/codeflash-github-actions",
"optimizing-with-codeflash/benchmarking"
]
},
{
Expand All @@ -62,21 +61,7 @@
}
]
}
],
"global": {
"anchors": [
{
"anchor": "GitHub",
"href": "https://github.com/codeflash-ai",
"icon": "github"
},
{
"anchor": "Discord",
"href": "https://www.codeflash.ai/discord",
"icon": "discord"
}
]
}
]
},
"logo": {
"light": "/images/codeflash_light.svg",
Expand All @@ -85,8 +70,14 @@
"navbar": {
"links": [
{
"label": "Contact",
"href": "mailto:[email protected]"
"label": "Discord",
"href": "https://www.codeflash.ai/discord",
"icon": "discord"
},
{
"label": "GitHub",
"href": "https://github.com/codeflash-ai/codeflash",
"icon": "github"
},
{
"label": "Blog",
Expand All @@ -113,7 +104,7 @@
"footer": {
"socials": {
"discord": "https://www.codeflash.ai/discord",
"github": "https://github.com/codeflash-ai",
"github": "https://github.com/codeflash-ai/codeflash",
"linkedin": "https://www.linkedin.com/company/codeflash-ai"
},
"links": [
Expand Down
93 changes: 39 additions & 54 deletions docs/getting-started/local-installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,31 +6,29 @@ icon: "download"

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.9 or above** 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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: Existing Tests are good to have.
We can include this in "good to have" category?


<Warning>
**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
venv\Scripts\activate # On Windows
```
</Warning>
<Steps>
<Step title="Install Codeflash">

You can install Codeflash locally for a project by running the following command in the project's virtual environment:
```bash
pip install codeflash
```
Expand All @@ -39,48 +37,39 @@ pip install codeflash
**Codeflash is a Development Dependency**

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.
Codeflash is intended to be used in development workflows locally and as part of CI.
Try to always use the latest version of Codeflash as it improves quickly.

<CodeGroup>
```toml Poetry
[tool.poetry.dependencies.dev]
codeflash = "^latest"
```

```bash uv
uv add --dev codeflash
```

```bash pip
pip install --dev codeflash
```bash poetry
poetry add codeflash@latest --group dev
```
</CodeGroup>
</Tip>
</Step>

<Step title="Generate a Codeflash API Key">
Codeflash uses cloud-hosted AI models to optimize your code. You'll need an API key to use it.
Codeflash uses cloud-hosted AI models and integrations with GitHub. You'll need an API key to authorize your access.

1. Visit the [Codeflash Web App](https://app.codeflash.ai/)
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

<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!
Codeflash offers a **free tier** with a limited number of optimizations. Perfect for trying it out on small projects!
</Note>
</Step>

<Step title="Run Automatic Configuration">
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
```

Expand All @@ -89,30 +78,31 @@ If you don't have a pyproject.toml file yet, the codeflash init command will ask
<Info>
**What's pyproject.toml?**

`pyproject.toml` is a configuration file that is used to specify build tool settings for Python projects.
pyproject.toml is the modern replacement for setup.py and requirements.txt files.
It's the new standard for Python package metadata.
`pyproject.toml` is a configuration file that is used to specify build and tool settings for Python projects.
`pyproject.toml` is the modern replacement for setup.py and requirements.txt files.
</Info>

When running `codeflash init`, you will see the following prompts:

```text
1. Enter your Codeflash API key:
2. Which Python module do you want me to optimize going forward? (e.g. my_module)
3. Where are your tests located? (e.g. tests/)
4. Which test framework do you use? (pytest/unittest)
1. Enter your Codeflash API key:
2. Install the GitHub app.
3. Which Python module do you want me to optimize going forward? (e.g. my_module)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: e.g. src/

4. Where are your tests located? (e.g. tests/)
5. Which test framework do you use? (pytest/unittest)
6. Install GitHub actions for Continuous optimization?
```
</Step>
</Steps>

After you have answered these questions, Codeflash will be configured for your project.
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.
After you have answered these questions, the Codeflash configuration will be saved in the `pyproject.toml` file.
To understand the configuration options, and set more advanced options, see the [Manual Configuration](/configuration) page.

### 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.
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
Expand All @@ -128,38 +118,37 @@ Once configured, you can start optimizing your code immediately:
# Optimize a specific function
codeflash --file path/to/your/file.py --function function_name

# Or optimize locally without creating a PR
codeflash --file path/to/your/file.py --function function_name --no-pr
# Or optimize all functions in your codebase
codeflash --all
```

<Tip>
**Pro tip**: Start with a single function to see how Codeflash works before running it on your entire codebase.
</Tip>
</Tab>

<Tab title="Example Project">
<Card title="🚀 Try Our Example Repository" icon="github" href="https://github.com/codeflash-ai/optimize-me">
Want to see Codeflash in action? Check out our **optimize-me** repository with real examples.
<Tab title="Optimize Example Project">
<Card title="🚀 Try optimizing our example repository" icon="github" href="https://github.com/codeflash-ai/optimize-me">
Want to see Codeflash in action and don't know what code to optimize? Check out our **optimize-me** repository with code ready to optimize.

**What's included:**
- Sample Python code with performance issues
- Tests for verification
- Pre-configured `pyproject.toml`
- Before/after optimization examples in PRs
</Card>

<Steps>
<Step title="Clone the Repository">
<Step title="Fork the Repository">
Fork the [optimize-me](https://github.com/codeflash-ai/optimize-me) repo to your GitHub account by clicking "Fork" on the top of the page. This allows Codeflash to open Pull Requests with the optimizations it found on your forked repo.
</Step>
<Step title="Clone the Forked Repository">
```bash
git clone https://github.com/codeflash-ai/optimize-me.git
git clone https://github.com/your_github_username/optimize-me.git
cd optimize-me
```
</Step>

<Step title="Set Up Environment">
```bash
python -m venv .venv
source .venv/bin/activate # or venv\Scripts\activate on Windows
source .venv/bin/activate
pip install -r requirements.txt
pip install codeflash
```
Expand Down Expand Up @@ -193,7 +182,9 @@ codeflash --all # optimize the entire repo
</Accordion>

<Accordion title="🧪 No optimizations found or debugging issues">
Use the `--verbose` flag for detailed output:
Do know that not all functions can be optimized as no optimization opportunities may exist for them. This is fine and expected.

To investigate further, use the `--verbose` flag for detailed output:
```bash
codeflash optimize --verbose
```
Expand All @@ -203,13 +194,7 @@ codeflash --all # optimize the entire repo
- 🚫 Why certain functions were skipped
- ⚠️ Detailed error messages
- 📊 Performance analysis results

<Tip>
**Common Reasons Functions Are Skipped:**
- Function is too simple (less than 3 lines)
- Function has no clear performance bottleneck
- Function contains unsupported constructs
</Tip>

</Accordion>

<Accordion title="🔍 No tests found errors">
Expand All @@ -223,7 +208,7 @@ codeflash --all # optimize the entire repo
pytest --collect-only

# Check your pyproject.toml configuration
cat pyproject.toml | grep -A 5 "\[tool.codeflash\]"
cat pyproject.toml | grep -A 8 "\[tool.codeflash\]"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

++ Can add verification withcodeflash --verify post setup.

```
</Accordion>
</AccordionGroup>
Expand All @@ -233,5 +218,5 @@ codeflash --all # optimize the entire repo

- 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)
- Set up [Pull Request Optimization](/optimizing-with-codeflash/codeflash-github-actions)
- Read [configuration options](/configuration) for advanced setups
16 changes: 9 additions & 7 deletions docs/getting-the-best-out-of-codeflash.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,28 +6,30 @@ sidebarTitle: "Best Practices"
keywords: ["best practices", "tips", "github actions", "tracer", "optimization", "workflow"]
---

# Getting the best out of Codeflash
Codeflash is a powerful tool; here are our recommendations based on how the Codeflash team and our customers use Codeflash.

Codeflash is a powerful tool; here are our recommendations based on how the Codeflash team uses Codeflash.
### Install the GitHub App and actions workflow

### Install the Github App and actions workflow

After you install Codeflash on an actively developed project, [installing the GitHub App](getting-started/codeflash-github-actions) and setting up the
GitHub Actions workflow will automatically optimize your code whenever new pull requests are opened. This ensures you get the best version of any changes you make to your code without any extra effort. We find that PRs are also the best time to review these changes, because the code is fresh in your mind.
After you install Codeflash on an actively developed project, [installing the GitHub Actions](optimizing-with-codeflash/codeflash-github-actions) will automatically optimize your code whenever new pull requests are opened. This ensures you get the best version of any changes you make to your code without any extra effort. We find that PRs are also the best time to review these changes, because the code is fresh in your mind.

### Find and optimize entire scripts with the Codeflash Tracer

Find the best results by running [Codeflash Optimize](optimizing-with-codeflash/trace-and-optimize) on your script to optimize it.
This internally runs a profiler, captures inputs to all the functions your script calls, and uses those inputs to create Replay tests and benchmarks.
The optimizations you get with this method, show you how much faster your workflow will get plus guarantee that your workflow won't break if you merge in the optimizations.

###

### Find optimizations on your whole codebase with `codeflash --all`

If you have a lot of existing code, run [`codeflash --all`](optimizing-with-codeflash/codeflash-all) to discover and fix any
slow code in your project. Codeflash will open new pull requests for any optimizations it finds, and you can review and merge them at your own pace.

It is first recommended to trace your tests to achieve higher quality optimizations with this approach

```bash
codeflash optimize --trace-only -m pytest tests/ ; codeflash --all
```


### Review the PRs Codeflash opens

Expand Down
Binary file added docs/images/codeflash_pr_suggestion_1.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/images/codeflash_social_card.png
View file
Open in desktop
Binary file not shown.
Loading
Loading