Skip to main content

Explain and Document Code with AI

Level: Intermediate · Time: 30–40 min · Category: Command line

Tags: Python · OpenAI SDK · Developer tools

Build a CLI that reads a Python file and asks the Research Computing OpenAI-compatible API to explain it in plain English, then to suggest docstrings. It is a useful tool for understanding inherited research code.

Prerequisites​

Confirm Python 3 and pip are available before you start:

python3 --version      # expect 3.9 or newer
python3 -m pip --version

If Python is not found, install it from python.org. On the supercomputer, load a Python module instead (for example module load python), then run the checks again.

What you will do​

  • Create a Python CLI workspace with the OpenAI SDK.
  • Read a source file and send it to the API.
  • Ask for a plain-English, function-by-function explanation.
  • Add a docstring-suggestion mode you review before applying.

Build it step by step​

1. Create the CLI workspace​

mkdir code-explainer
cd code-explainer
python3 -m venv .venv
source .venv/bin/activate
pip install openai python-dotenv rich
Keep this out of Git

If you track this project with Git, do not commit your virtual environment or any secrets. Create a .gitignore file in the project folder with at least these lines:

.gitignore
.venv/
.env
__pycache__/

.venv/ is large and specific to your machine, and .env holds your API key — neither belongs in a shared repository. New to Git? See Track a New Project with Git.

2. Add API connection values​

Your program needs three values to reach the API: your API key, the gateway URL, and a model ID. You keep them in a small text file named .env so they stay out of your code — and out of Git.

What is a .env file, and where does it go?

A .env ("dot-env") file is a plain text file that stores settings as NAME=value lines, one per line. Programs read it at startup so you never have to paste secrets like API keys directly into your code.

  • The filename is literally .env — a leading dot with nothing before it (not config.env or .env.txt).
  • It goes in your project folder: the same directory you just created, where the .venv lives and where you run your commands.
  • The python-dotenv package loads it with load_dotenv(), which looks for .env in the folder you run the program from.
  • Because it holds a secret, never commit it to Git (see the note below).

Create a new file named .env in your project folder — in VS Code use File → New File, or run code .env in the terminal — then paste these three lines and replace the placeholders:

.env
OPENAI_API_KEY="paste-your-key-here"
OPENAI_BASE_URL="https://openai.rc.asu.edu/v1"
RC_LLM_MODEL="paste-model-id-here"
Where do the values come from?

Get your API key and a valid model ID from the LLM API guide. The OPENAI_BASE_URL above is already correct for the Research Computing gateway.

  • Use the /v1 base URL, not the full /chat/completions URL, for the Python SDK.
  • Use a model ID that appears in the portal model list for your account.
  • Keep .env out of Git: add a line containing .env to your .gitignore (see Track a New Project with Git).

3. Pick a file to explain​

Use a small Python file you already have, or create a short sample so you can see the tool work.

cat > sample.py <<'PY'
def load_values(path):
    with open(path) as f:
        return [float(line) for line in f if line.strip()]

def mean(values):
    return sum(values) / len(values)

if __name__ == "__main__":
    import sys
    print(mean(load_values(sys.argv[1])))
PY

4. Ask for the first explainer​

You are helping me build a beginner Python CLI that explains a Python file using an OpenAI-compatible API.

Project goal:
- Command: python explain.py sample.py
- Read the source file as text.
- Send it to the chat completions API through the OpenAI Python SDK.
- Print a plain-English explanation of what the file does, function by function.
- Read OPENAI_API_KEY, OPENAI_BASE_URL, and RC_LLM_MODEL from a .env file.

Constraints:
- Keep the first version in one file named explain.py.
- Add friendly errors for a missing file, missing API key, or API failure.

Please:
1. Create explain.py.
2. Explain how the source is sent to the model.
3. Show the command to run it on sample.py.

5. Add a docstring mode​

Please add a --docstrings mode to explain.py:

Behavior:
- With --docstrings, ask the model to suggest a Google-style docstring for each function.
- Print the suggestions to the terminal only. Do not modify the source file.

Constraints:
- Keep the plain-English explanation as the default mode.
- Explain how to run the new mode.

6. Add one feature of your own​

Please add one focused feature to explain.py:

Feature:
- Accept a folder path and explain each .py file in it, one at a time.

Constraints:
- Keep single-file mode working.
- Keep the code beginner-readable.
- Explain how to test the folder mode.

More prompts to try​

  • Add a --summary mode that prints a one-paragraph overview of the whole file.
  • Ask the model to flag risky patterns such as bare except or hard-coded paths.
  • Add a --write option that inserts reviewed docstrings, and remind me to commit first.

Troubleshooting​

  • For large files, ask the assistant to split the file by function with the ast module before sending it.
  • Always read AI-suggested docstrings. They can describe intent incorrectly.
  • If you add a --write option, commit your file to Git first so you can undo unwanted edits.
  • If you get a model error, use a model ID from the portal model list for your account.

Next steps​