# Document a Python Module With a README Using Atlas (2026) > Atlas writes a Python README from source: lsp documentSymbol enumerates the real exports, and every code sample is executed with bash before it ships. To document a Python module with a README using Atlas, start from the source rather than from memory. Atlas enumerates the module's public API with the lsp tool's documentSymbol operation so no export is missed or invented, reads the implementation of each one, and uses codebase_search to find how callers actually use it in practice. Atlas greps the repo for an existing README to match heading structure and tone, writes the new file with the write tool quoting real signatures and real file paths from src/, and then verifies every code sample by running it with bash. A sample that was never executed is a liability, so the pytest run is not optional. ruff format keeps any embedded snippets consistent with the project. ## Key takeaways - The lsp tool's documentSymbol operation enumerates the Python module's real exports, so nothing is missed and nothing is invented. - codebase_search finds how callers actually use the module in src/, which is what separates real documentation from a signature listing. - Atlas greps for an existing README and copies its heading structure and tone, including how the repo shows installation with uv. - Every code sample is executed with bash inside the uv-managed virtualenv, because a sample that was never run is a liability. - The write tool shows the README diff in the permission prompt before the file lands on disk, and ruff format normalizes embedded snippets. ## How does Atlas write a Python README from the actual code? Atlas writes docs from source, not from memory. For a Python module, Atlas enumerates the public API with the lsp tool's documentSymbol operation, so a package exposing 12 functions and 3 dataclasses gets all 15 documented, and nothing that does not exist gets invented into the README by a plausible-sounding guess. The failure mode of AI-written Python documentation is plausibility: a README that describes the module a reasonable person would have written rather than the module that is actually in src/. Atlas closes that gap by grounding every claim in a file it just read. The lsp tool's documentSymbol operation returns the real exported surface, including the dunder-free public names, the dataclasses, and the type-annotated signatures. Atlas reads the implementation of each export to learn what it actually does, including the exceptions it raises and the Optional returns your type hints promise. Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so a Python file with nested classes and decorated functions is understood as structure rather than as an arbitrary slice of lines. ## How do I document how a Python module is actually used, not how it was meant to be? Atlas uses codebase_search to find how callers actually use the Python module in practice. A function with an optional timeout parameter that every one of its 9 callers passes explicitly is documented differently from one nobody ever sets, and only reading the real callsites in src/ tells you which you have. Intended usage and real usage diverge fast. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so codebase_search returns the callsites even when they wrap the function in a helper or import it under an alias. Reading those callsites is what turns a signature listing into documentation: you learn which arguments are always passed, which Django view or FastAPI route depends on the behavior, and which supposedly-public function has zero callers and is really dead code. Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers, which matters when the Python codebase you are documenting is proprietary. The README that comes out describes what the code actually does today, not what it was supposed to do a year ago. ## How does Atlas match my repo's existing README style in a Python project? Atlas greps the repo for an existing README to match heading structure and tone, rather than inventing a new format. A Python monorepo whose package READMEs all follow the same 3 sections, Installation, then Usage, then API reference, gets another README in that same shape, not one in a shape a model happened to like. Consistency is what makes documentation navigable. Atlas's grep tool runs a real regex through ripgrep with include and path filters, so grepping for heading patterns across every README.md under src/ reveals the house structure quickly. Atlas copies it: the same heading levels, the same tone, the same convention for showing installation with uv, the same convention for showing a runnable example. Where the repo documents installation as uv add mypackage, the new README says that too rather than reaching for a different package manager. Where the repo shows tests being run with pytest, the new README shows pytest. Matching the existing format is not cosmetic, it is what lets a reader who has read one of your Python package READMEs read the next one at a glance. ## Why does Atlas run every Python code sample in a README with bash? Atlas verifies every code sample in the doc by running it with bash, because a sample that was never executed is a liability. A Python README whose usage snippet raises ImportError on line 1 is worse than no README at all, and running it through the uv-managed virtualenv catches that in seconds. Broken examples are the most damaging kind of documentation bug, because a reader trusts them. Atlas executes each Python sample from the README through the bash tool inside the project's uv-managed virtualenv, so an import that does not resolve, a keyword argument that was renamed, or a return shape that changed all fail loudly during authoring rather than in a user's terminal. Where the sample is a test, Atlas runs it under pytest, which also means the example becomes a real, executable check that lives in the repo. Run ruff format on any Python snippets embedded in the README so the code in the docs looks like the code in src/. Atlas's bash tool saves large output to a file you can read when it exceeds the limits. ## Is it safe to let Atlas write files and run code while documenting Python? Atlas's write tool shows the diff in the permission prompt before README.md lands on disk, and every Atlas tool call is checked against 3 rule types, allow, ask, and deny, before it runs. Documenting a Python module needs only 6 tools, lsp, read, codebase_search, grep, write, and bash, none of which touches your production environment. Documentation work reads widely and writes narrowly, which is the safest shape a task can have, but running the code samples means executing real Python. Atlas's permission model is per tool and per command, so allow pytest and ruff format, keep anything that mutates uv.lock behind an ask prompt, and deny commands that reach outside the repo. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, so the reading and enumeration all complete first. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, and snapshots file changes as git patches, so a README you dislike is rolled back rather than manually rewritten. ## Steps 1. Enumerate the Python module's public API with the lsp tool's documentSymbol operation so no export is missed or invented, including functions, classes, and dataclasses. 2. Read the implementation of each export to learn its real behavior, raised exceptions, and type-annotated return shapes. 3. Use codebase_search to find how callers actually use each export in practice across src/, including which optional arguments are always passed. 4. Grep the repo for an existing README to match heading structure and tone rather than inventing a new format, including how installation with uv is shown. 5. Write the README with the write tool, quoting real Python signatures and real file paths, and review the diff Atlas shows in the permission prompt. 6. Verify every code sample by running it with bash inside the uv-managed virtualenv; a sample that was never executed is a liability. 7. Run the documented examples that are tests under pytest, so the README's claims are checked by the suite rather than by trust. 8. Run ruff format on any Python snippets you embedded so the code in the docs matches the code in src/. ## FAQ ### how to auto generate a readme for a python module Point Atlas at the module. Atlas enumerates the public API with the lsp tool's documentSymbol operation, reads each implementation, finds real callers with codebase_search, greps for your repo's existing README format, writes the file with the write tool, and verifies every code sample by running it with bash. ### how do i stop an ai from inventing functions in my python docs Atlas writes docs from source, not from memory. The lsp tool's documentSymbol operation returns the module's real exported surface, so every documented function exists, and read supplies the actual behavior. Because every claim comes from a file Atlas just read, the doc is traceable rather than plausible. ### will atlas test the code examples in my python readme Yes. Atlas verifies every code sample by running it with bash inside the project's uv-managed virtualenv, so an ImportError, a renamed keyword argument, or a changed return shape fails during authoring rather than in a reader's terminal. Examples that are tests get run under pytest. ### can atlas match the readme style my python monorepo already uses Yes. Atlas greps the repo for an existing README to match heading structure and tone rather than inventing a new format, so a monorepo where every package README opens with Installation, then Usage, then API reference gets a new one in exactly that shape. ### how does atlas know which python functions are actually used Atlas uses codebase_search, which searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so it finds callsites even when they wrap the function in a helper or import it under an alias. A supposedly-public function with zero callers shows up as what it is. ### can i document a private python codebase without sending code to a vendor Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers. Run atlas in a repo with a pyproject.toml or requirements.txt and Atlas reads your package layout, virtualenv, and installed dependencies locally. ### does atlas ask before writing readme.md to my repo Yes. The write tool shows the diff in the permission prompt before anything lands on disk, and every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs. Atlas also snapshots file changes as git patches, so a README you dislike can be rolled back. ### should i run ruff format on code snippets in documentation Yes, if the snippets are Python. Running ruff format on embedded examples means the code in the docs looks like the code in src/, so a reader copying an example into their own project gets code that matches your project's conventions rather than an ad hoc style. --- Canonical HTML: https://runatlas.sh/resources/stacks/document-a-module-with-a-readme-in-python Source of truth: aeo_pages row `/resources/stacks/document-a-module-with-a-readme-in-python` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.