Sphinx Documents Your Code. Who Documents Your App?

Let’s set the scene. You’ve spent three weeks building a dashboard for your SaaS app. The backend is clean Python. FastAPI routes, Pydantic models, well-typed service layers. You run sphinx-apidoc and get beautiful API reference pages. Every class, every method, every parameter documented.

Then your first user signs up and emails you: “How do I create a project?”

They don’t care about your ProjectService.create() method signature. They want a screenshot of the button they need to click.

I’ve seen this happen over and over. And I think it’s one of the biggest blind spots in the Python ecosystem right now.

The Two Kinds of Documentation Nobody Talks About

Let’s get specific. There are two fundamentally different types of documentation, and most developers only automate one of them.

Code documentation is what Sphinx, MkDocs, and pdoc handle. It describes your API surface. These tools parse your docstrings, pull type annotations, and generate reference pages. They’re essential if you’re building a library. No argument there.

But there’s a second kind: app documentation. This is the stuff your actual end users read.

• Getting started guides
• Feature walkthroughs with screenshots
• Step by step “click here, then here” instructions
• FAQ pages and troubleshooting articles
• Help center pages that show up when someone clicks the ”?” icon

If you’re shipping a web application, and let’s be honest, that’s most of what Python developers are building in 2026, this second kind is what your users actually need.

And almost nobody automates it.

Why This Gap Exists

The reason is architectural. Let me explain.

Sphinx and MkDocs work by reading your source code. They introspect modules, parse docstrings, and render what they find. A typical Sphinx setup looks like this:

# conf.py (Sphinx)
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx_autodoc_typehints',
]
autodoc_default_options = {
    'members': True,
    'undoc-members': True,
}

This generates documentation about your code. But your web app’s user facing behavior lives in a completely different layer. Your GET /dashboard endpoint might render a complex React page with filters, modals, and data tables. None of that shows up in your docstrings. None of it.

MkDocs with Material theme gets you closer to good looking help docs. But you’re still writing every page by hand. And here’s the real problem: manual docs decay faster than anyone can maintain them.

Your team pushes code multiple times a day. By the time you finish writing a guide for a feature, that feature has changed. The screenshots are wrong. The button labels are different. The flow has an extra step now. I’ve lived this. It’s exhausting.

A Different Starting Point: Your Running App

Here’s where things get interesting. Let’s talk about the Model Context Protocol (MCP) and why it changes the equation.

MCP lets AI tools interact with your actual development environment. Not as a text generator guessing at code, but as a participant that can inspect, navigate, and observe your running application. An MCP based documentation tool doesn’t start with your source files. It starts with your app.

Think about the difference. Instead of parsing def create_project(self, name: str, owner_id: UUID) and generating a method reference, an MCP tool can:

• Discover your app’s routes by analyzing your codebase
• Navigate to each route in a real headless browser
• Capture screenshots of what your users actually see
• Annotate UI elements with numbered callouts
• Write help articles describing the interface, not the implementation

This is the approach KodaDocs takes. It’s an open source Python CLI that connects to Claude Code as an MCP server. Instead of reading your docstrings, it analyzes your codebase to discover routes, captures screenshots of your running application with Playwright, and assembles a full VitePress documentation site.

The output isn’t API references. It’s help documentation with real screenshots, organized by feature, describing what your users see when they use your app.

How the Workflow Actually Looks

Let’s get into the technical details. A typical KodaDocs workflow has four steps:

# Install KodaDocs
pip install kodadocs

# In Claude Code, the MCP tools become available:
# 1. detect_framework    identifies your stack (Next.js, Django, Flask, etc.)
# 2. discover_routes     finds all user facing routes from source code
# 3. capture_screenshots takes real screenshots via Playwright
# 4. assemble_vitepress  builds the final documentation site

The framework detection is automatic. It reads your project structure, identifies whether you’re running Django, Flask, FastAPI, Next.js, React, SvelteKit, Laravel, or any of 18+ supported frameworks, and adapts its route discovery strategy accordingly.

The screenshot capture is real. Not mocked, not generated. Playwright launches a headless browser, navigates to each route, and captures what’s actually rendered. UI elements get numbered callouts so the written documentation can reference them directly.

The final output is a complete VitePress help center with:

• Full text search built in
• Sidebar navigation organized by feature
• Mobile responsive layout
• Getting started guides generated from your actual onboarding flow
• Feature documentation for every route in your app

You go from zero docs to a live help site in under three minutes. I’m not exaggerating. That’s the actual benchmark.

This Isn’t an Either/Or

I want to be clear about something. Sphinx and MkDocs aren’t going anywhere, and they shouldn’t.

If you maintain a Python library, sphinx-autodoc is still the right tool. If you want a hand written docs site with excellent search and versioning, MkDocs Material is hard to beat. I use both of these tools myself. They’re great at what they do.

But if you’re an indie developer or a small team shipping a web app, you probably need both kinds of documentation, and you have time for neither.

Here’s how I think about it:

• The API reference for your internal SDK? Let Sphinx generate it from your docstrings. That’s what it’s built for.
• The help docs your users see when they click the ”?” icon? That’s a different problem entirely. It needs a different solution.

The two tools complement each other. They don’t compete.

Where This Is Heading

The concept of continuous documentation, docs that regenerate as your code changes and stay in sync without manual intervention, has been discussed for years. But it’s never quite delivered. CI/CD pipelines handle testing, linting, and deployment. Documentation remains a manual step for most teams.

MCP based tooling changes this because it can interact with your application the way a user would. By looking at it, clicking through it, and describing what it sees. That’s not a theoretical improvement. It’s a practical one you can use today.

I think we’re going to see more tools built on this pattern. Documentation is one of the first areas where MCP’s capabilities matter, but it won’t be the last. Any workflow that requires understanding what a user sees in a running application is a candidate.

Get Started

If you’re building a web app in Python and your documentation strategy starts and ends with Sphinx, you might be documenting the wrong thing. Your code is well described. Your app might not be.

KodaDocs is open source on GitHub. It’s worth a look if you’ve been putting off writing help docs for the app you’ve already built. Install it, point it at your running app, and let’s see what comes out.

Your users will thank you.