doc-drift is a command-line checker described by its builder as a way to find Python functions and classes in Markdown code examples that no longer match a repository. It compares syntax rather than importing or running the project, so it can flag missing names and signature changes without executing inspected code. It is most useful when documentation snippets are intended to reflect real Python code—not when they are illustrative pseudocode.
What doc-drift checks in README files
In a September 16, 2026 DEV Community article, author and builder sunnydachs describes doc-drift as scanning repository Markdown files for fenced code blocks, then comparing Python functions and classes in those blocks with the repository’s code. The tool reports three kinds of findings:
As an Amazon Associate I earn from qualifying purchases.
- SIGNATURE DRIFT: A documented function is present in the code, but its argument names differ.
- MISSING: A documented function or class cannot be found in the repository.
- UNPARSEABLE: A block is not valid Python, such as pseudocode or a placeholder. The author characterizes this as informational.
These checks address a specific form of documentation drift: code examples that name constructs that have been removed or whose signatures have changed. They do not establish that an example is correct in meaning or that it runs successfully.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
How its AST-based approach works
According to sunnydachs, doc-drift uses Python’s standard ast module to compare syntax. The author says, “It never imports or executes your code — it compares at the syntax-tree level.” (DEV Community article, September 16, 2026.) The article states Python 3.11 or newer is required.
#1 Best Overall
That static approach avoids running repository code during inspection, but it also defines what the checker can see. The stated matching rule permits examples to simplify real code by omitting arguments or class methods; it should not invent functions or methods that the implementation lacks. In the author’s formulation: “Omit arguments — allowed. Invent arguments or functions that don’t exist in the code — forbidden.” This is doc-drift’s design rule, not a general standard for all documentation checks.
How to run it and read the output
The article shows these invocations:
doc-drift
doc-drift /path/to/repo --jsonThe first command is shown for scanning a repository; the second supplies a repository path and requests machine-readable JSON output. The article does not establish current installation instructions or provide a confirmed release, so these examples should not be taken as a complete setup guide.
Its sample output includes Markdown-file and code-block counts, a signature mismatch, and a JSON summary. Those are illustrative values, not expected results or a performance benchmark. JSON may be useful when building an automated workflow, but the article does not document a maintained GitHub Action or a specific CI integration.
Where it can help—and where it can mislead
Best fit: executable examples that should track the code
doc-drift is aimed at documentation trees where Python snippets are meant to mirror repository functions and classes. In that setting, a missing name or changed argument list can be a useful prompt to update the example or reconsider the implementation.
Illustrations can produce false positives
The checker cannot determine whether a snippet is intended as executable documentation or simply illustrates an idea. A README example that deliberately uses a made-up function may therefore be reported as missing. Treat such findings as review items, not automatic proof that the documentation is wrong.
Python-only and name-based
The article says other-language code blocks may be counted but are not checked. It also says default values and type annotations are ignored. The comparison targets names, removals, and argument-name or arity differences; it does not validate behavior, semantic correctness, or whether the documented call works in context.
What the author’s scan does—and does not—show
sunnydachs reports scanning 1,692 Markdown files and 4,451 code blocks in a repository, finding one genuine drift: documentation showed a function with two arguments while the implementation had moved to one. The author also says an overly broad default exclusion caused false positives and was corrected. These counts and outcomes are the author’s account; the repository identity, methodology, and results were not independently verified in the article. They are evidence of one reported run, not a measure of how common README drift is across software projects.
How to decide whether a checker fits your documentation
Before adopting any documentation checker, assess it against the way your examples are written:
- Language coverage: Does it inspect the languages used in your docs, or only Python?
- Execution model: Does it execute examples, analyze syntax statically, or combine approaches? Consider the safety and coverage trade-offs.
- Depth: Does it check names and signatures, or also verify behavior and meaning?
- Illustrations: Can you distinguish runnable examples from pseudocode, or will you need to review false positives?
- Automation: Is the report format usable in your workflow, and is a supported CI integration actually documented?
- Maintenance: Are installation steps, releases, and project status verifiable for the version you plan to use?
The linked article presents doc-drift’s design and examples, but does not independently establish its current release status, license, installation process, or a maintained CI integration. Verify those details in the project repository before relying on it in a team workflow.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
