Docstrings explain individual functions. A user guide must explain what someone can accomplish, what they need first, and what to do when something fails. This sprint turns a small set of Python docstrings into one publishable guide, with checks that keep generated instructions tied to real behavior.
1. Pick one user task and its source functions
Start with a concrete outcome: download a report as a CSV file. Identify the public functions involved, their tests, and any existing setup instructions. Keep this first guide limited to one successful path and its most likely failures.
Write a one-sentence acceptance criterion: a new user can configure access, download an existing report, save its contents, and recognize an invalid report identifier. This gives you a practical boundary for extraction, drafting, and review.
2. Extract signatures and docstrings without importing modules
For a Python package, use the standard library's ast module to parse source files. Walk function definitions, collect their arguments and defaults, and retrieve docstrings with ast.get_docstring. Record each function's file path and starting line so reviewers can trace claims back to their source.
Parsing avoids import-time side effects, but it does not resolve every runtime detail. Flag decorators, dynamically generated interfaces, and inherited behavior for manual review. Keep extraction output as structured records containing the symbol name, signature, docstring, and source location.
3. Build a verified contract for the report download
Suppose your extracted signature is fetch_report(report_id, format="csv"). Its docstring states that supported formats are csv and json, the return value is bytes, unsupported formats raise ValueError, and missing reports raise ReportNotFoundError. Preserve those facts explicitly in your drafting input.
- Task: Download an existing report.
- Required input: A valid report identifier.
- Default: CSV output when format is omitted.
- Output: Bytes that the caller must save or process.
- Known failures: Unsupported format and missing report.
Do not infer authentication, retries, pagination, or permissions from this contract. Find separate evidence for each prerequisite, and mark missing information as a documentation gap.
4. Ask for a task-focused draft with evidence boundaries
Give your drafting model the verified contract, relevant setup documentation, and the acceptance criterion. Request prerequisites, numbered actions, an example, expected results, and troubleshooting. Tell it to distinguish documented facts from unresolved questions and to omit unsupported behavior.
SwiftRelay fits here if you want to run the drafting step through an OpenAI-compatible SDK. Configure its base URL as https://api.fastapirelay.com/v1 and choose a model such as Claude Sonnet 5.5. Keep your API key in an environment variable and send only source material approved for external processing.
Sign up for SwiftRelay to try this workflow with the small gift credit provided to new accounts; usage is billed per token.
5. Turn function details into executable reader actions
Review the draft for missing transitions. A function description may say that bytes are returned without explaining that the user needs to write them to a file opened in binary mode. Add that action because it follows directly from the verified return type.
Use one consistent sample report identifier, clearly labeled as a placeholder. Explain where users obtain a real identifier using verified project documentation. Include the package's actual import path and access setup only after checking them against the repository. Never let a plausible-looking import become an untested instruction.
6. Run the example and check each failure path
Execute the guide's example in a clean environment using a test account and a known report. Confirm that the output file exists and that its contents match the requested format. Record the package version used for this check.
Then test an unsupported format and a nonexistent report. Verify the documented exception types against observed behavior. If implementation and docstrings disagree, open a tracked issue and resolve the discrepancy before publishing instructions that depend on it.
7. Publish the guide with a maintenance trigger
Finish with a reader-focused pass: can someone follow the guide without opening the source? Check every prerequisite, placeholder, expected result, and recovery action. Keep unresolved questions out of the published procedure.
Store the guide alongside its source references and executable example. Add a review trigger when the referenced functions, their tests, or setup requirements change. Your finished artifact is a maintained path from a user's goal to a verified result.