{"id":29927523,"url":"https://github.com/crypdick/auto_docs_editor","last_synced_at":"2025-08-02T13:11:06.415Z","repository":{"id":304725827,"uuid":"1017756672","full_name":"crypdick/auto_docs_editor","owner":"crypdick","description":"AutoDocsEditor makes documentation conform to the Google Docs Style Guide","archived":false,"fork":false,"pushed_at":"2025-07-30T21:00:17.000Z","size":1252,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-31T00:03:44.714Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crypdick.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-11T03:55:03.000Z","updated_at":"2025-07-30T21:00:21.000Z","dependencies_parsed_at":"2025-07-18T06:00:32.458Z","dependency_job_id":null,"html_url":"https://github.com/crypdick/auto_docs_editor","commit_stats":null,"previous_names":["crypdick/auto_google_style","crypdick/auto_docs_editor"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/crypdick/auto_docs_editor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crypdick%2Fauto_docs_editor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crypdick%2Fauto_docs_editor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crypdick%2Fauto_docs_editor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crypdick%2Fauto_docs_editor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crypdick","download_url":"https://codeload.github.com/crypdick/auto_docs_editor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crypdick%2Fauto_docs_editor/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268394071,"owners_count":24243350,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-02T13:11:03.156Z","updated_at":"2025-08-02T13:11:06.391Z","avatar_url":"https://github.com/crypdick.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AutoDocsEditor\n\n`AutoDocsEditor` helps your documentation conform to the [Google Developer Documentation Style Guide](https://developers.google.com/style) 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.\n\n![Screenshot of AutoDocsEditor in action](assets/screenshot.png)\n\n\n## Quick start\n\nTo get started, export your OpenAI key (or put it in a `.env` file):\n\n```shell\n    export OPENAI_API_KEY=\"YOUR_API_KEY\"\n```\n\nRun the `auto_docs_edit.py` script against a target Markdown document:\n\n```shell\n    uv run --script auto_docs_edit.py docs/your_article.md\n```\n\nThis script processes the Markdown file against every page of the style guide (stored locally in the `style/` directory). The script 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.\n\nNote: we recommend using `o4-mini` for better results.\n\n### Skip style rules\n\nIf you are resuming a run, you can skip style rules you have already processed:\n\n```shell\n    uv run --script auto_docs_edit.py \\\n        --skip-through commas.md docs/your_article.md\n```\n\nThis example skips every style rule **up to and including** the `commas.md` file.\n\nYou can also press the **`ESC`** key to interrupt the current task and skip to the next task.\n\n### Final pass sweep\n\nAfter 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:\n\n```shell\n    uv run --script auto_docs_edit.py --final-pass docs/your_article.md\n```\n\nThe script will process **only** those style guide pages whose filenames end with a `+`, for example `00-tone+.md`.\n\n### YOLO mode (non-interactive)\n\nRun the script with `--yolo` to automatically accept every proposed edit and skip the manual review pauses:\n\n```shell\n    uv run --script auto_docs_edit.py --yolo docs/your_article.md\n```\n\nYOLO mode is not recommended because mistakes will compound.\n\n### Bulk PR automation\n\nIf you want to **batch-apply** the style rules and open one draft pull-request per document, use `bulk_pr_autodocs.py`.\n\n1. Ensure you have a local clone of the GitHub repository you want to patch.\n2. Export a **personal access token** with `repo` and `gist` scopes (required to push branches and create secret gists):\n\n```shell\nexport GITHUB_TOKEN=\"YOUR_GITHUB_PAT\"\n```\n\nor put it in a `.env` file:\n```text\nGITHUB_TOKEN=YOUR_GITHUB_PAT\n```\n\n3. Create a *greenlist* text file that lists the Markdown paths (relative to the repo root) you want to process, for example:\n\n```text\n# greenlist.txt=\ndocs/getting-started.md\ndocs/advanced/configuration.md\n```\n\n4. Run the bulk script:\n\n```shell\nuv run --script bulk_pr_autodocs.py \\\n  --repo /path/to/local/clone \\\n  --greenlist greenlist.txt\n```\n\nFlags:\n* `--dry-run` – print actions without touching GitHub.\n* `--continue-on-error` – keep processing even if one document fails.\n* `--base-branch` and `--remote` – customise the target branch/remote.\n\nFor every listed file the script will:\n\n1. Create a branch `docs/auto-edit-\u003cslug\u003e` inside your clone.\n2. Run `auto_docs_edit.py` in YOLO mode.\n3. Push the branch and open a **draft** PR against `\u003cbase-branch\u003e`.\n4. Upload the LLM session log to a **secret gist** and link to it from the PR description.\n5. Archive a copy of the log under `logs/bulk_pr_logs/`.\n\n## Incident logs\n\nIf an edit fails to apply (for example, the script can't find the snippet), the script records a log file under `incidents/`, so you can inspect what went wrong.\n\n## Differences to the official style guide\n\n- Moved some guides that are irrelevant for my use case to `archive/`.\n- Deleted Google- and Android-specific style rules.\n- Simplified some style rules to make them more \"atomic\" and less monolithic.\n- 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.\").\n- Added a few style precedence rules to enforce an ordering of the style guides.\n- Dropped preference for `_` over `*` for italics.\n- 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.\n- Added some personal style rules. These personal style rules are prefixed with `PERSONAL-`.\n- Removed HTML-specific style rules.\n\n## Set style rule precedence\n\nThe 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.\n\n## Planned features\n\n- [ ] Support for applying the script to Jupyter notebooks.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrypdick%2Fauto_docs_editor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrypdick%2Fauto_docs_editor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrypdick%2Fauto_docs_editor/lists"}