AI-Generated Python Project Documentation: A Practical Automation Workflow

Writing documentation is something almost no one volunteers to do. READMEs describe APIs that went stale long ago, docstrings are stuck two refactors behind—this isn't an isolated case but the norm for most Python projects. One developer maintaining a 40-module image processing package filled in the entire project's documentation from scratch in a single afternoon—not by working overtime, but with an "AI draft + human review" pipeline.

The core idea of this workflow isn't complicated: let AI handle the boring 80% and keep human judgment for yourself. But its value lies in how the author lays out every step and every place where AI fell flat.

Break It Down First: What "Documentation" Actually Means in a Python Project

Before automating, you must divide documentation into four layers, because AI and tools excel at completely different things:

• Docstrings: Mechanical descriptions at the module, class, and function level. This is what AI is best at.
• API reference: A site rendered from docstrings. This is a tooling problem, not a writing problem, and it should never be manually maintained.
• Guides and README: Why the project exists, how to install it, runnable examples. AI can produce decent drafts here, but examples must actually run.
• The "why": Design decisions, pitfalls encountered, migration notes. This remains human territory—AI can rewrite what you tell it, but it doesn't know what decision you made at 2 a.m.

Respect this layering, and automation becomes meaningful: AI handles the first and third layers, static site tools take over the second, and you write the fourth yourself without shortcuts.

Toolchain: Every Choice Verified Against Official Docs

The author emphasizes that the tool versions and features here were checked one by one, not copied from an outdated list.

pydoc ships with Python. python -m pydoc mypkg prints docstring documentation directly, and pydoc -w mypkg outputs an HTML file. Zero configuration but a crude interface—the author uses it only as a quick check that docstrings parse, not as a deliverable.

pdoc is currently at version 16.0.0. pdoc ./mypkg opens API documentation in the browser with live reload as you edit; pdoc ./mypkg -o ./docs exports static HTML. Docstrings are rendered as Markdown, with native understanding of Google style and numpydoc style, and type annotations automatically become clickable links. There's no config file to write—that's its entire design philosophy.

MkDocs + mkdocstrings is the choice for product-style documentation sites. MkDocs generates a static site from Markdown and a single mkdocs.yml, with a built-in dev server; the mkdocstrings plugin injects live Python objects into pages—write ::: plus an identifier to render docstrings, with cross-referencing capability similar to Sphinx's intersphinx. Here's a detail the author specifically points out: the mkdocstrings website currently carries a maintenance-mode banner. It still works and is widely deployed (used by large projects like Ansible), but you should factor this into long-term planning.

Sphinx is the industry heavyweight solution, reStructuredText-first, suited to large multi-project documentation sets. It's too heavy a machine for a single library, so it's outside this article's workflow, but that doesn't stop you from swapping it in as the renderer.

Google style and numpydoc style are the two mainstream Python docstring conventions. Google style uses indented sections like Args:, Returns:, and Raises: to describe function information; numpydoc style uses underlined Parameters, Returns, and Raises sections, and the latter is more common in the scientific computing community (NumPy, SciPy). pdoc natively parses both styles, meaning you can render section content into structured parameter tables and return-value descriptions without extra configuration. If your project uses other styles (such as Sphinx's reST field lists), pdoc's rendering will suffer, and you'll need to standardize your docstring conventions.

mkdocstrings and intersphinx cross-referencing is a key capability for large documentation sites. intersphinx lets you link from one project's docs to another project's API pages (such as the Python standard library or third-party libraries), avoiding manual maintenance of external links. Although mkdocstrings is not a Sphinx plugin, it can achieve similar results through its handlers configuration—it reads live Python objects directly, so class names in type annotations can automatically resolve to links pointing to the corresponding documentation page, provided the referenced object is also processed by mkdocstrings within the same documentation set.

Manual vs AI-Assisted: A Comparison Table

Task	Fully manual	AI-assisted	What the author does now
Docstrings for ~40 modules	3–5 hours of focused typing	First draft in minutes, plus review time	AI drafts, human deletes the lies
API reference site	One pdoc command, or an hour of MkDocs config	Same tools, AI writes the config too	pdoc for libraries, MkDocs for product docs
Tutorials and how-to guides	The part you never finish	Solid drafts from code and tests, examples need verification	AI drafts, every example edited until it runs
Updating after refactors	Manual, silently rots	Regenerated on demand from current code	Regenerated at every minor release
Review burden	None—you wrote it yourself	Real: AI confidently makes things up	doctest + 30 minutes of human review

The most noteworthy thing in this table isn't the efficiency numbers but the last row—the cost of AI assistance is review burden, and there's no avoiding it.

The Four-Step Workflow, Step by Step

Step 1: Generate docstrings

Once the module API is stable, have AI do a first pass over the source: generate Google-style docstrings for every public function, class, and module, taking parameter types from the actual signature rather than inventing them. The author's hard rule: if a docstring mentions a parameter that doesn't exist in the signature, delete it outright.

Step 2: Render the API reference

For a pure library project, run pdoc ./mypkg -o ./docs and commit the output—it's that fast. For a product-style site, have AI generate mkdocs.yml and the documentation skeleton, then let mkdocstrings inject live API objects. The author sees AI writing this config as exactly where the tool's value shows: mkdocs.yml syntax is tedious to learn, but the model already knows it inside out.

Step 3: Draft the README and guides

Feed the package's entry points and test suite together to AI, and ask for a README draft: installation instructions, three runnable examples, a troubleshooting section. The test suite is key here—an example anchored in a real passing test is an example that runs.

Step 4: The review gate (the real source of trustworthiness)

Every generated docstring and example must pass the same gate: run doctest (python -m doctest -v mypkg/*.py), build the docs and click every link, and read docstring diffs like you read code diffs. 30 minutes versus 5 hours of hand-writing, and this step cannot be skipped.

doctest is a testing framework bundled with the Python standard library. It extracts interactive examples beginning with >>> from docstrings, executes them, and compares the output against what's written in the docstring. python -m doctest -v mypkg/*.py runs these examples module by module and prints detailed results. Its value lies in turning examples from "looks like it runs" into "verified to run": any misspelled parameter, broken import path, or output format mismatch surfaces as a test failure. The limitation is that doctest only validates examples inside >>> blocks; ordinary Markdown code blocks in the README aren't automatically included—to cover them, use the --doctest-glob option or pytest's --doctest-modules plugin. Putting doctest into CI ensures every example AI regenerates goes through the same verification gate.

Where AI-Generated Documentation Still Falls Flat

The author devotes a separate section to "the honest part," because "AI writes documentation" demos never include these. Typical problems he caught in real output:

• Nonexistent parameters. The model documents the signature it thinks exists, not the one you actually shipped—functions with recently changed signatures are especially prone to this.
• Confidently asserted exception lists. "Raises ValueError when input is invalid"—when the function raises nothing at all. A docstring that lies about error behavior is worse than no docstring.
• Outdated intent. A docstring describing the function's old behavior survives refactors because nothing forces it to change with the code. Regenerate per version, or it rots just like hand-written docs.
• Almost-runnable examples. Off-by-one parameters, deleted imports, deprecated call paths. Any example not in doctest, assume it doesn't run.
• Adjective soup. "Efficiently processes..."—delete on sight. Documentation describes behavior, not enthusiasm.

Who This Workflow Isn't For

The author is equally candid here: if your "project" is just a few one-off scripts and notebooks, a single README suits you better than a documentation site; if you're not documenting a Python stack, this pipeline is Python-first; if you don't plan to review anything, AI-generated documentation will hand you confident nonsense that quietly erodes user trust—better to write nothing at all; if you maintain a large multi-project documentation set, Sphinx plus intersphinx is already the right answer—swap out the renderer and keep AI drafting.

A Note on Tool Selection

The author mentions using AI Doc Generator as the engine for steps one and three, and explicitly discloses that this is an affiliate link with a $49 one-time purchase price. This is a single-source personal recommendation; readers should evaluate paid tools themselves before choosing one. The workflow itself isn't tied to any specific tool—any general-purpose LLM can handle docstring drafting and README first drafts.

The Honest Conclusion

AI can't replace your reviewer, and it shouldn't replace your judgment. But it can absolutely replace the blank page, and the blank page has always been the real enemy. The workflow that survives in real projects is boring and repeatable: AI generates docstrings, pdoc or MkDocs plus mkdocstrings renders the reference, guides are drafted from the test suite, then run doctest and spend 30 minutes reviewing the diff. About 30 minutes of review per release instead of losing a weekend per project, and documentation stays bound to the code rather than drifting away.

Start with a small package. If the first review pass catches nothing, either AI has finally earned your trust—or you didn't read carefully enough.

One-line Summary

AI drafts docstrings and guides, tools render the API reference, doctest plus human review backstop it all—30 minutes per release to end documentation rot.

Paragraph Summary

The article presents an "AI draft + human review" Python documentation workflow. The author first splits documentation into four layers: docstrings, API reference, guides and README, and design decisions, noting that AI excels at drafting the first two and the third, static site tools handle rendering, and the "why" must be written by humans. The toolchain section verifies the use cases for pydoc, pdoc 16.0.0, MkDocs plus mkdocstrings (the latter in maintenance mode), and Sphinx. The workflow has four steps: AI generates docstrings, tools render the API reference, README and guides are drafted from entry points and the test suite, then run doctest and spend 30 minutes reviewing the diff. The article also candidly lists five typical AI failure modes (fabricated parameters, false exceptions, outdated intent, non-running examples, adjective soup) and explains that this workflow doesn't suit scattered scripts, non-Python stacks, no-review scenarios, or large documentation sets already using Sphinx.