Skip to content

Commit 1585da7

Browse files
jayhackcodegen-bot
jayhack
and
codegen-bot
authored
docs: fixes homepage + many guides (#165)
# Motivation <!-- Why is this change necessary? --> # Content <!-- Please include a summary of the change --> # Testing <!-- How was the change tested? --> # Please check the following before marking your PR as ready for review - [ ] I have added tests for my changes - [ ] I have updated the documentation or added new documentation as needed - [ ] I have read and agree to the [Contributor License Agreement](../CLA.md) --------- Co-authored-by: codegen-bot <[email protected]>
1 parent 8e62e70 commit 1585da7

File tree

11 files changed

+327
-1111
lines changed

11 files changed

+327
-1111
lines changed

‎docs/cli/reset.mdx

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: "Reset Command"
3+
sidebarTitle: "reset"
4+
icon: "rotate-left"
5+
iconType: "solid"
6+
---
7+
8+
The `reset` command performs a hard reset of your git repository while carefully preserving all files in the `.codegen` directory. This is useful for undoing codemod changes while keeping your codemod implementations intact.
9+
10+
## Usage
11+
12+
```bash
13+
codegen reset
14+
```
15+
16+
## What it Does
17+
18+
When you run `codegen reset`, it:
19+
20+
1. Backs up all files in `.codegen` directory, preserving their content and staged/unstaged status
21+
2. Performs a hard reset (`git reset --hard HEAD`) on the repository
22+
3. Restores all `.codegen` files to their previous state, including their git staging status
23+
4. Removes untracked files (except those in `.codegen`)
24+
25+
<Note>
26+
This is more sophisticated than `git checkout .` as it:
27+
- Preserves both staged and unstaged changes in `.codegen`
28+
- Handles deleted files correctly
29+
- Removes untracked files (like `git clean`) while protecting `.codegen`
30+
</Note>
31+
32+
## Examples
33+
34+
Reset after testing a codemod:
35+
```bash
36+
# Run your codemod
37+
codegen run organize-imports
38+
39+
# If the changes aren't what you wanted
40+
codegen reset # Reverts changes but keeps your codemod implementation
41+
```
42+
43+
44+
<Warning>
45+
This command performs a hard reset and removes untracked files. Make sure you have committed any changes you want to keep outside of `.codegen`.
46+
</Warning>

‎docs/images/set-interpreter.png

271 KB
Loading

‎docs/images/system-prompt.png

173 KB
Loading

‎docs/introduction/getting-started.mdx

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,11 @@ icon: "bolt"
55
iconType: "solid"
66
---
77

8-
Follow our step-by-step tutorial to get up and running with Codegen.
8+
A quick tour of Codegen in a Jupyter notebook.
99

1010
## Installation
1111

12-
We recommend using [uv](https://github.com/astral-sh/uv) to install Codegen's CLI globally.
13-
14-
First, install `uv` if you haven't already:
15-
16-
```bash
17-
curl -LsSf https://astral.sh/uv/install.sh | sh
18-
```
19-
20-
Then install Codegen:
12+
Install [`codegen` on pypi](https://pypi.org/project/codegen/) via [uv](https://github.com/astral-sh/uv):
2113

2214
```bash
2315
uv tool install codegen
@@ -28,17 +20,21 @@ uv tool install codegen
2820
keeping its dependencies isolated.
2921
</Note>
3022

23+
3124
## Quick Start with Jupyter
3225

33-
The [codgen notebook](/cli/notebook) command creates a virtual environment and opens a jupyter notebook for quick prototyping. This is often the fastest way to get up and running.
26+
The [codgen notebook](/cli/notebook) command creates a virtual environment and opens a Jupyter notebook for quick prototyping. This is often the fastest way to get up and running.
27+
28+
<Tip>
29+
Prefer working in your IDE? See [IDE Usage](/introduction/ide-usage)
30+
</Tip>
3431

3532

3633
```bash
3734
# Navigate to your repository
3835
cd path/to/git/repository
3936

4037
# Initialize codegen and launch Jupyter
41-
codegen init
4238
codegen notebook
4339
```
4440

‎docs/introduction/ide-usage.mdx

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
title: "Using Codegen in Your IDE"
3+
sidebarTitle: "IDE Usage"
4+
icon: "window"
5+
iconType: "solid"
6+
---
7+
8+
Get up and running with Codegen programs in IDEs like VSCode, Cursor and PyCharm.
9+
10+
<Tip>Make sure to [install and initialize](/introduction/installation) Codegen with `codegen init`</Tip>
11+
12+
## Configuring your IDE Interpreter
13+
14+
Codegen creates a custom Python environment in `.codegen/.venv`. Configure your IDE to use this environment for the best development experience.
15+
16+
<AccordionGroup>
17+
<Accordion title="VSCode, Cursor and Windsurf" icon="window-maximize">
18+
1. Open the Command Palette (Cmd/Ctrl + Shift + P)
19+
2. Type "Python: Select Interpreter"
20+
<img src="/images/set-interpreter.png" />
21+
3. Choose "Enter interpreter path"
22+
4. Navigate to and select:
23+
```bash
24+
.codegen/.venv/bin/python
25+
```
26+
27+
Alternatively, create a `.vscode/settings.json`:
28+
```json
29+
{
30+
"python.defaultInterpreterPath": "${workspaceFolder}/.codegen/.venv/bin/python",
31+
"python.analysis.extraPaths": [
32+
"${workspaceFolder}/.codegen/.venv/lib/python3.11/site-packages"
33+
]
34+
}
35+
```
36+
</Accordion>
37+
38+
<Accordion title="PyCharm" icon="python">
39+
1. Open PyCharm Settings/Preferences
40+
2. Navigate to "Project > Python Interpreter"
41+
3. Click the gear icon ⚙️ and select "Add"
42+
4. Choose "Existing Environment"
43+
5. Set interpreter path to:
44+
```bash
45+
.codegen/.venv/bin/python
46+
```
47+
48+
For better type hints:
49+
1. Right-click on `.codegen/.venv`
50+
2. Mark Directory as > Sources Root
51+
</Accordion>
52+
53+
<Accordion title="Troubleshooting" icon="wrench">
54+
Common issues and solutions:
55+
56+
- **Missing Completions**: Make sure the interpreter is correctly set and the environment has `codegen` installed
57+
- **Import Errors**: Verify the environment is activated and Python path includes the virtual environment
58+
- **Wrong Python Version**: Check that you're using Python 3.11 or higher in `.codegen/.venv`
59+
60+
Run this to verify your environment:
61+
```bash
62+
.codegen/.venv/bin/python -c "import codegen; print(codegen.__version__)"
63+
```
64+
</Accordion>
65+
</AccordionGroup>
66+
67+
68+
## Create a New Codemod
69+
70+
Generate the boilerplate for a new code manipulation program using [codegen create](/cli/create):
71+
72+
```bash
73+
codegen create organize-types \
74+
-d "Move all TypeScript types to \
75+
into a centralized types.ts file"
76+
```
77+
78+
<Tip>
79+
Passing in `-d --description` will get an LLM expert to compose an initial version for you. This requires a Github account registered on [codegen.sh](https://codegen.sh)
80+
</Tip>
81+
82+
This will:
83+
1. Create a new codemod in `.codegen/codemods/organize_types/`
84+
2. Generate a custom `system-prompt.txt` based on your task
85+
3. Set up the basic structure for your program
86+
87+
<Note>
88+
The generated codemod includes type hints and docstrings, making it easy to get IDE autocompletion and documentation.
89+
</Note>
90+
91+
## Iterating with Chat Assistants
92+
93+
When you do `codegen init`, you will receive a [system prompt optimized for AI consumption](/introduction/work-with-ai) at `.codegen/codegen-system-prompt.txt`.
94+
95+
If you reference this file in "chat" sessions with Copilot, Cursor, Cody, etc., the assistant will become fluent in Codegen.
96+
97+
<Frame>
98+
<img src="/images/system-prompt.png" />
99+
Collaborating with Cursor's assistant and the Codegen system prompt
100+
</Frame>
101+
102+
In addition, when you [create](/cli/create) a codemod with "-d", Codegen generates an optimized system prompt in `.codegen/codemods/{name}/{name}-system-prompt.txt`. This prompt contains:
103+
- Relevant Codegen API documentation
104+
- Examples of relevant transformations
105+
- Context about your specific task
106+
107+
<Tip>
108+
You can also drag and drop the system prompt ([available here](/introduction/work-with-ai))file directly into chat windows like ChatGPT or Claude for standalone help.
109+
</Tip>
110+
111+
## Running and Testing Codemods
112+
113+
```bash
114+
# Run => write changes to disk
115+
codegen run organize-types
116+
117+
# Reset changes on disk
118+
codegen reset
119+
```
120+
121+
<Tip>You can also run the program directly via `.codegen/.venv/bin/python path/to/codemod.py` or via your editor's debugger</Tip>
122+
123+
## Viewing Changes
124+
125+
We recommend viewing changes in your IDE's native diff editor.
126+
127+
128+
## What's Next
129+
130+
<CardGroup cols={2}>
131+
<Card
132+
title="Explore Tutorials"
133+
icon="graduation-cap"
134+
href="/tutorials/at-a-glance"
135+
>
136+
See real-world examples of codemods in action.
137+
</Card>
138+
<Card
139+
title="Codegen Guides"
140+
icon="book"
141+
href="/building-with-codegen/at-a-glance"
142+
>
143+
Learn about Codegen's core concepts and features
144+
</Card>
145+
</CardGroup>

‎docs/introduction/installation.mdx

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
title: "Installation"
3+
sidebarTitle: "Installation"
4+
icon: "download"
5+
iconType: "solid"
6+
---
7+
8+
Install and set up Codegen in your development environment.
9+
10+
## Prerequisites
11+
12+
We recommend using [uv](https://github.com/astral-sh/uv) for installation. If you haven't installed `uv` yet:
13+
```bash
14+
curl -LsSf https://astral.sh/uv/install.sh | sh
15+
```
16+
17+
## Installing Codegen
18+
19+
Install the Codegen CLI globally:
20+
21+
```bash
22+
uv tool install codegen
23+
```
24+
25+
26+
<Note>
27+
This makes the `codegen` command available globally in your terminal, while keeping its dependencies isolated.
28+
</Note>
29+
30+
## Quick Start
31+
32+
Let's walk through a simple example of using Codegen in a project:
33+
34+
1. Navigate to your repository:
35+
```bash
36+
cd path/to/your/project
37+
```
38+
39+
2. Initialize Codegen in your project:
40+
```bash
41+
codegen init
42+
```
43+
44+
This creates a `.codegen/` directory with:
45+
```bash
46+
.codegen/
47+
├── .venv/ # Python virtual environment (gitignored)
48+
├── config.toml # Project configuration
49+
├── codemods/ # Your codemod implementations
50+
├── jupyter/ # Jupyter notebooks for exploration
51+
└── codegen-system-prompt.txt # AI system prompt
52+
```
53+
54+
3. Create your first codemod with [codegen create](/cli/create):
55+
```bash
56+
codegen create organize-imports \
57+
-d "Sort and organize imports according to PEP8"
58+
```
59+
<Note>
60+
The `-d` flag in `codegen create` generates an AI-powered implementation. This requires a Github account registered on [codegen.sh](https://codegen.sh)
61+
</Note>
62+
63+
64+
65+
4. Run your codemod with [codegen run](/cli/run):
66+
```bash
67+
codegen run organize-imports
68+
```
69+
70+
5. Reset any filesystem changes (excluding `.codegen/*`) with [codegen reset](/cli/reset):
71+
```bash
72+
codegen reset
73+
```
74+
75+
## Next Steps
76+
77+
<CardGroup cols={2}>
78+
<Card
79+
title="IDE Integration"
80+
icon="window"
81+
href="/introduction/ide-usage"
82+
>
83+
Learn how to use Codegen effectively in VSCode, Cursor, and other IDEs.
84+
</Card>
85+
<Card
86+
title="Tutorials"
87+
icon="graduation-cap"
88+
href="/tutorials/at-a-glance"
89+
>
90+
Follow step-by-step tutorials for common code transformation tasks.
91+
</Card>
92+
<Card
93+
title="Work with AI"
94+
icon="microchip"
95+
href="/introduction/work-with-ai"
96+
>
97+
Leverage AI assistants like Copilot, Cursor and Devin
98+
</Card>
99+
<Card
100+
title="Guides"
101+
icon="hammer"
102+
href="/building-with-codegen/at-a-glance"
103+
>
104+
Learn more about building with Codegen
105+
</Card>
106+
107+
</CardGroup>
108+
109+
<Note>
110+
For more help, join our [community Slack](/introduction/community) or check the [FAQ](/introduction/faq).
111+
</Note>

‎docs/introduction/overview.mdx

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,9 @@ for function in codebase.functions:
2121
if not function.usages:
2222
# Auto-handles references and imports to maintain correctness
2323
function.remove()
24+
25+
# Fast, in-memory code index
26+
codebase.commit()
2427
`
2528

2629
export const code = `def foo():
@@ -35,7 +38,7 @@ def baz():
3538

3639
<iframe
3740
width="100%"
38-
height="320px"
41+
height="370px"
3942
scrolling="no"
4043
src={`https://codegen.sh/embedded/codemod/?code=${encodeURIComponent(
4144
metaCode
@@ -46,6 +49,12 @@ def baz():
4649
className="rounded-xl"
4750
></iframe>
4851

52+
<Note>
53+
Codegen handles complex refactors while maintaining correctness, enabling a broad set of advanced code manipulation programs.
54+
</Note>
55+
56+
<Tip>Codegen works with both Python and Typescript/JSX codebases. Learn more about language support [here](/building-with-codegen/language-support).</Tip>
57+
4958
## Installation
5059

5160
```bash

0 commit comments

Comments
 (0)