AutoDocsEditor

AutoDocsEditor helps your documentation conform to the Google Developer Documentation Style Guide by using large language models (LLMs). This is a large style guide (71 pages!), so the AutoDocsEditor breaks up the job into stages, proposing incremental edits to a document. This makes the process of hand-checking a long document against 71 individual style rules less tedious.

Supports both Markdown files (.md) and Jupyter notebooks (.ipynb)!

Quick start

To get started, export your OpenAI key (or put it in a .env file):

export OPENAI_API_KEY="YOUR_API_KEY"

Install the package:

uv sync

Interactive TUI Mode (Recommended)

Run the interactive TUI to review and accept/reject each proposed edit:

# Using the unified entry point
uv run python main.py tui docs/your_article.md

# Or using the direct command
uv run auto-docs-tui docs/your_article.md

The TUI provides a visual diff interface where you can:

• Review each proposed edit with before/after comparison
• Accept or reject individual edits (keyboard shortcuts: a to accept, r to reject)
• Skip to the next style guide (s)
• See the reason for each edit

CLI Mode (Automatic)

Run the CLI mode to automatically apply edits (original behavior):

# Using the unified entry point
uv run python main.py cli docs/your_article.md

# Or using the direct command
uv run auto-docs-edit docs/your_article.md

Both modes process the Markdown file against every page of the style guide (stored locally in the style/ directory). The CLI mode pauses between each set of edits, giving you the opportunity to review the proposed edits and commit the incremental changes before moving on to the next set of style rules. The script itself doesn't touch Git.

Note: we recommend using o4-mini for better results.

Jupyter Notebook Support

AutoDocsEditor supports Jupyter notebooks via Jupytext:

# Edit a notebook directly - works with both TUI and CLI modes
uv run auto-docs-tui notebooks/tutorial.ipynb
uv run auto-docs-edit notebooks/tutorial.ipynb

How it works:

1. The tool converts your .ipynb to MyST Markdown format using Jupytext
2. Applies style guide edits to the Markdown representation
3. Automatically syncs changes back to the notebook
4. Cleans up temporary files

Skip style rules

If you are resuming a run, you can skip style rules you have already processed:

uv run auto-docs-tui --skip-through commas.md docs/your_article.md
# or
uv run auto-docs-edit --skip-through commas.md docs/your_article.md

This example skips every style rule up to and including the commas.md file.

In TUI mode, you can also press s to skip to the next style guide, or q to quit.

Final pass sweep

After you have iterated through the full style guide once and made additional manual edits, you can run a quick compliance sweep over only the most error-prone rules:

uv run auto-docs-tui --final-pass docs/your_article.md
# or
uv run auto-docs-edit --final-pass docs/your_article.md

The script will process only those style guide pages whose filenames end with a +, for example 00-tone+.md.

YOLO mode (CLI only, non-interactive)

Run the CLI with --yolo to automatically accept every proposed edit and skip the manual review pauses:

uv run auto-docs-edit --yolo docs/your_article.md

YOLO mode is not recommended because mistakes will compound. Consider using the TUI mode instead for better control.

Bulk PR automation

If you want to batch-apply the style rules and open one draft pull-request per document, use bulk_pr_autodocs.py.

1. Ensure you have a local clone of the GitHub repository you want to patch.
2. Export a personal access token with repo and gist scopes (required to push branches and create secret gists):

export GITHUB_TOKEN="YOUR_GITHUB_PAT"

or put it in a .env file:

GITHUB_TOKEN=YOUR_GITHUB_PAT

3. Create a greenlist text file that lists the Markdown paths (relative to the repo root) you want to process, for example:

# greenlist.txt=
docs/getting-started.md
docs/advanced/configuration.md

4. Run the bulk script:

uv run --script bulk_pr_autodocs.py \
  --repo /path/to/local/clone \
  --greenlist greenlist.txt

Flags:

• --dry-run – print actions without touching GitHub.
• --continue-on-error – keep processing even if one document fails.
• --base-branch and --remote – customise the target branch/remote.

For every listed file the script will:

1. Create a branch docs/auto-edit-<slug> inside your clone.
2. Run auto_docs_edit.py in YOLO mode.
3. Push the branch and open a draft PR against <base-branch>.
4. Upload the LLM session log to a secret gist and link to it from the PR description.
5. Archive a copy of the log under logs/bulk_pr_logs/.

Differences to the official style guide

• Moved some guides that are irrelevant for my use case to archive/.
• Deleted Google- and Android-specific style rules.
• Simplified some style rules to make them more "atomic" and less monolithic.
• Added a few LLM hints to prevent common LLM mistakes while applying the style guides (for example, "Do not apply this style guide to code blocks.").
• Added a few style precedence rules to enforce an ordering of the style guides.
• Dropped preference for _ over * for italics.
• Removed internal links between style rule pages, since the LLM applies one set of style rules at a time and also can't follow the links.
• Added some personal style rules. These personal style rules are prefixed with PERSONAL-.
• Removed HTML-specific style rules.

Set style rule precedence

The order in which the style rules are applied is important because subsequent edits may revert previous edits. The default order is alphabetic. Therefore, to enforce an ordering, you can add prefixes to the style guide names. The script applies the prefixes 00-, 01-, 02- in that order, before non-numeric style guides. Conversely, the script applies z- last.