devDocs 2.0.7__tar.gz → 4.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- devdocs-4.0.0/LICENSE +21 -0
- devdocs-4.0.0/PKG-INFO +210 -0
- devdocs-4.0.0/README.md +171 -0
- devdocs-4.0.0/devDocs.egg-info/PKG-INFO +210 -0
- devdocs-4.0.0/devDocs.egg-info/SOURCES.txt +110 -0
- devdocs-4.0.0/devDocs.egg-info/entry_points.txt +2 -0
- devdocs-4.0.0/devDocs.egg-info/requires.txt +10 -0
- devdocs-4.0.0/devDocs.egg-info/top_level.txt +1 -0
- devdocs-4.0.0/devdocs/__init__.py +13 -0
- devdocs-4.0.0/devdocs/__main__.py +5 -0
- devdocs-4.0.0/devdocs/capabilities.py +182 -0
- devdocs-4.0.0/devdocs/cli.py +1063 -0
- devdocs-4.0.0/devdocs/compose.py +565 -0
- devdocs-4.0.0/devdocs/config.py +459 -0
- devdocs-4.0.0/devdocs/context.py +245 -0
- devdocs-4.0.0/devdocs/demo.py +12 -0
- devdocs-4.0.0/devdocs/errors.py +214 -0
- devdocs-4.0.0/devdocs/generate.py +1253 -0
- devdocs-4.0.0/devdocs/graph.py +1459 -0
- devdocs-4.0.0/devdocs/history.py +149 -0
- devdocs-4.0.0/devdocs/ignore.py +591 -0
- devdocs-4.0.0/devdocs/index/__init__.py +10 -0
- devdocs-4.0.0/devdocs/index/cache.py +123 -0
- devdocs-4.0.0/devdocs/index/chunk.py +198 -0
- devdocs-4.0.0/devdocs/index/db.py +461 -0
- devdocs-4.0.0/devdocs/index/embed.py +183 -0
- devdocs-4.0.0/devdocs/index/ledger.py +114 -0
- devdocs-4.0.0/devdocs/index/search.py +152 -0
- devdocs-4.0.0/devdocs/issues.py +111 -0
- devdocs-4.0.0/devdocs/legacy.py +267 -0
- devdocs-4.0.0/devdocs/llm/__init__.py +128 -0
- devdocs-4.0.0/devdocs/llm/anthropic_sdk.py +126 -0
- devdocs-4.0.0/devdocs/llm/budget.py +356 -0
- devdocs-4.0.0/devdocs/llm/catalog.py +493 -0
- devdocs-4.0.0/devdocs/llm/client.py +423 -0
- devdocs-4.0.0/devdocs/llm/factory.py +53 -0
- devdocs-4.0.0/devdocs/llm/http.py +688 -0
- devdocs-4.0.0/devdocs/llm/providers.py +773 -0
- devdocs-4.0.0/devdocs/llm/stop.py +32 -0
- devdocs-4.0.0/devdocs/parse/__init__.py +206 -0
- devdocs-4.0.0/devdocs/parse/generic.py +964 -0
- devdocs-4.0.0/devdocs/parse/languages.py +539 -0
- devdocs-4.0.0/devdocs/parse/masking.py +666 -0
- devdocs-4.0.0/devdocs/parse/python.py +867 -0
- devdocs-4.0.0/devdocs/plan.py +562 -0
- devdocs-4.0.0/devdocs/prompting.py +993 -0
- devdocs-4.0.0/devdocs/prompts/__init__.py +1 -0
- devdocs-4.0.0/devdocs/prompts/architecture.md +29 -0
- devdocs-4.0.0/devdocs/prompts/file.md +26 -0
- devdocs-4.0.0/devdocs/prompts/module.md +26 -0
- devdocs-4.0.0/devdocs/render/__init__.py +783 -0
- devdocs-4.0.0/devdocs/render/assets/filter.js +100 -0
- devdocs-4.0.0/devdocs/render/assets/style.css +794 -0
- devdocs-4.0.0/devdocs/render/diagram.py +556 -0
- devdocs-4.0.0/devdocs/render/html.py +984 -0
- devdocs-4.0.0/devdocs/render/markdown.py +526 -0
- devdocs-4.0.0/devdocs/render/model.py +365 -0
- devdocs-4.0.0/devdocs/render/pdf/__init__.py +726 -0
- devdocs-4.0.0/devdocs/render/pdf/check.py +1205 -0
- devdocs-4.0.0/devdocs/render/pdf/external.py +189 -0
- devdocs-4.0.0/devdocs/render/pdf/fonts.py +145 -0
- devdocs-4.0.0/devdocs/render/pdf/layout.py +1044 -0
- devdocs-4.0.0/devdocs/render/pdf/writer.py +547 -0
- devdocs-4.0.0/devdocs/render/style.py +1128 -0
- devdocs-4.0.0/devdocs/render/text.py +141 -0
- devdocs-4.0.0/devdocs/retrieve.py +148 -0
- devdocs-4.0.0/devdocs/scan.py +460 -0
- devdocs-4.0.0/pyproject.toml +97 -0
- devdocs-4.0.0/tests/test_anthropic_sdk.py +454 -0
- devdocs-4.0.0/tests/test_budget.py +526 -0
- devdocs-4.0.0/tests/test_capabilities.py +123 -0
- devdocs-4.0.0/tests/test_cli.py +2705 -0
- devdocs-4.0.0/tests/test_client.py +737 -0
- devdocs-4.0.0/tests/test_compose.py +434 -0
- devdocs-4.0.0/tests/test_config.py +1105 -0
- devdocs-4.0.0/tests/test_db.py +613 -0
- devdocs-4.0.0/tests/test_diagram.py +241 -0
- devdocs-4.0.0/tests/test_embed.py +479 -0
- devdocs-4.0.0/tests/test_errors.py +176 -0
- devdocs-4.0.0/tests/test_export.py +375 -0
- devdocs-4.0.0/tests/test_generate.py +2354 -0
- devdocs-4.0.0/tests/test_graph.py +1224 -0
- devdocs-4.0.0/tests/test_history.py +272 -0
- devdocs-4.0.0/tests/test_html.py +958 -0
- devdocs-4.0.0/tests/test_http.py +886 -0
- devdocs-4.0.0/tests/test_ignore.py +487 -0
- devdocs-4.0.0/tests/test_issues.py +77 -0
- devdocs-4.0.0/tests/test_legacy.py +477 -0
- devdocs-4.0.0/tests/test_markdown.py +1265 -0
- devdocs-4.0.0/tests/test_masking.py +601 -0
- devdocs-4.0.0/tests/test_model.py +179 -0
- devdocs-4.0.0/tests/test_parse_generic.py +547 -0
- devdocs-4.0.0/tests/test_parse_python.py +766 -0
- devdocs-4.0.0/tests/test_pdf.py +752 -0
- devdocs-4.0.0/tests/test_pdf_check.py +227 -0
- devdocs-4.0.0/tests/test_pdf_external.py +154 -0
- devdocs-4.0.0/tests/test_pdf_fonts.py +40 -0
- devdocs-4.0.0/tests/test_pdf_layout.py +249 -0
- devdocs-4.0.0/tests/test_pdf_writer.py +140 -0
- devdocs-4.0.0/tests/test_persistence.py +305 -0
- devdocs-4.0.0/tests/test_plan.py +1343 -0
- devdocs-4.0.0/tests/test_prompting.py +1447 -0
- devdocs-4.0.0/tests/test_providers.py +801 -0
- devdocs-4.0.0/tests/test_release.py +835 -0
- devdocs-4.0.0/tests/test_render_text.py +155 -0
- devdocs-4.0.0/tests/test_render_writer.py +1392 -0
- devdocs-4.0.0/tests/test_retrieval.py +312 -0
- devdocs-4.0.0/tests/test_scan.py +492 -0
- devdocs-4.0.0/tests/test_style.py +113 -0
- devdocs-2.0.7/PKG-INFO +0 -204
- devdocs-2.0.7/README.md +0 -171
- devdocs-2.0.7/devDocs/cli.py +0 -119
- devdocs-2.0.7/devDocs.egg-info/PKG-INFO +0 -204
- devdocs-2.0.7/devDocs.egg-info/SOURCES.txt +0 -11
- devdocs-2.0.7/devDocs.egg-info/entry_points.txt +0 -2
- devdocs-2.0.7/devDocs.egg-info/requires.txt +0 -2
- devdocs-2.0.7/devDocs.egg-info/top_level.txt +0 -1
- devdocs-2.0.7/pyproject.toml +0 -56
- devdocs-2.0.7/setup.py +0 -2
- {devdocs-2.0.7 → devdocs-4.0.0}/devDocs.egg-info/dependency_links.txt +0 -0
- /devdocs-2.0.7/devDocs/__init__.py → /devdocs-4.0.0/devdocs/py.typed +0 -0
- {devdocs-2.0.7 → devdocs-4.0.0}/setup.cfg +0 -0
devdocs-4.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Gantavya Bansal
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
devdocs-4.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: devDocs
|
|
3
|
+
Version: 4.0.0
|
|
4
|
+
Summary: Documentation from source code: exact facts from parsers, model prose only where it adds something, on a hard budget. No dependencies.
|
|
5
|
+
Author-email: Gantavya Bansal <gantavyaoo@gmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/bgantavya/devDocs
|
|
8
|
+
Project-URL: Repository, https://github.com/bgantavya/devDocs
|
|
9
|
+
Project-URL: Issues, https://github.com/bgantavya/devDocs/issues
|
|
10
|
+
Project-URL: Documentation, https://github.com/bgantavya/devDocs/tree/v4/docs
|
|
11
|
+
Keywords: cli,documentation,docs-generator,llm,gemini,claude,markdown,static-analysis,code-documentation,zero-dependency
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: Information Technology
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
24
|
+
Classifier: Topic :: Documentation
|
|
25
|
+
Classifier: Topic :: Software Development :: Documentation
|
|
26
|
+
Classifier: Typing :: Typed
|
|
27
|
+
Requires-Python: >=3.11
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
License-File: LICENSE
|
|
30
|
+
Provides-Extra: anthropic
|
|
31
|
+
Requires-Dist: anthropic>=1.0; extra == "anthropic"
|
|
32
|
+
Provides-Extra: dev
|
|
33
|
+
Requires-Dist: ruff>=0.16; extra == "dev"
|
|
34
|
+
Requires-Dist: mypy>=1.19; extra == "dev"
|
|
35
|
+
Requires-Dist: bandit>=1.8; extra == "dev"
|
|
36
|
+
Requires-Dist: pip-audit>=2.9; extra == "dev"
|
|
37
|
+
Requires-Dist: coverage>=7.10; extra == "dev"
|
|
38
|
+
Dynamic: license-file
|
|
39
|
+
|
|
40
|
+
# devdocs
|
|
41
|
+
|
|
42
|
+
Documentation from source code: exact facts from parsers, model prose only where it adds something, on a hard budget. No dependencies.
|
|
43
|
+
|
|
44
|
+
[](https://github.com/bgantavya/devDocs/actions/workflows/publish.yml?query=branch%3Av4)
|
|
45
|
+
[](https://pypi.org/project/devDocs/)
|
|
46
|
+
[](https://pypi.org/project/devDocs/)
|
|
47
|
+
[](https://github.com/bgantavya/devDocs/blob/v4/LICENSE)
|
|
48
|
+
|
|
49
|
+
devdocs is a command-line tool that writes the documentation of a code base: an overview of the architecture, a page for each module (each directory of source files), and a page for each source file other than tests and vendored or generated code. Parsers supply the facts. A model, Google Gemini or Anthropic Claude, writes prose only where it adds something, within a hard budget.
|
|
50
|
+
|
|
51
|
+
## Why devdocs
|
|
52
|
+
|
|
53
|
+
- **Facts come from parsers.** Parsers for Python, JavaScript, TypeScript, Go, Rust and Java read each file's public symbols, signatures, docstrings and imports, and the pages print signatures as the source writes them. The model writes prose around these facts; it never supplies them.
|
|
54
|
+
- **Prose only where it adds something.** devdocs ranks the files and gives prose to those where it adds most. A file its own docstrings already document, or one that ranks low, gets a page from facts alone, called a stub, at no cost. `devdocs estimate --explain` shows each file's plan and the reason for it.
|
|
55
|
+
- **A hard budget, priced first.** A run spends at most $0.50 unless you set another limit; a limit of 0 means no limit, not zero spend. Each request reserves its worst-case price before it is sent, so a run stays within the limit, and `devdocs estimate` prices a run before you pay for anything.
|
|
56
|
+
- **Cached and resumable.** Every usable answer is kept in `.devdocs/` in the project, and reused for free while its prompt and model stay the same ([costs.md](https://github.com/bgantavya/devDocs/blob/v4/docs/costs.md#what-a-re-run-pays-for)). A stopped run resumes where it stopped.
|
|
57
|
+
- **Markdown, HTML and PDF.** Markdown pages, a static HTML site that needs no server, and PDF from a built-in engine, or from an installed Chrome, Chromium, Edge or WeasyPrint for all of Unicode.
|
|
58
|
+
- **Gemini or Claude.** Gemini is the default; Claude is one setting away.
|
|
59
|
+
- **No dependencies.** Python 3.11 or newer and its standard library, nothing else. devdocs also installs from npm, and runs as a container image.
|
|
60
|
+
|
|
61
|
+
## Quick start
|
|
62
|
+
|
|
63
|
+
Install devdocs with [pipx](https://pipx.pypa.io/):
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
pipx install "devDocs>=4"
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
devdocs needs Python 3.11 or newer. If pipx runs on an older Python, name a newer one, as in `pipx install --python python3.13 "devDocs>=4"`. If you have no Python 3.11 or newer, [uv](https://docs.astral.sh/uv/) downloads one as it installs devdocs: `uv tool install --python 3.13 "devDocs>=4"`. [The install guide](https://github.com/bgantavya/devDocs/blob/v4/docs/install.md) covers every method, and upgrading and removing.
|
|
70
|
+
|
|
71
|
+
Check the setup with `devdocs doctor --offline`. It sends nothing, and marks the API key `!!` until you set one.
|
|
72
|
+
|
|
73
|
+
Get an API key from [Google AI Studio](https://aistudio.google.com/apikey) for Gemini, or from the [Anthropic Console](https://console.anthropic.com/) for Claude. In bash or zsh, run the line for your provider, paste the key and press Enter. `read -s` keeps the key off the screen and out of your shell history.
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
read -rs GEMINI_API_KEY && export GEMINI_API_KEY
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
For Claude, the line also selects the provider:
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY DEVDOCS_PROVIDER=anthropic
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
In PowerShell, use `$env:GEMINI_API_KEY = 'your-key'`, or for Claude `$env:ANTHROPIC_API_KEY = 'your-key'; $env:DEVDOCS_PROVIDER = 'anthropic'`, with your key in place of `your-key`.
|
|
86
|
+
|
|
87
|
+
Then, at the root of your project, write a starter `devdocs.toml`:
|
|
88
|
+
|
|
89
|
+
```sh
|
|
90
|
+
devdocs init
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
For Claude, run `devdocs init --provider anthropic` instead, so the file selects Claude too. `init` also adds `.devdocs/`, where devdocs keeps what it buys, to your `.gitignore`; it creates no `.gitignore` if you have none.
|
|
94
|
+
|
|
95
|
+
If your project already has a `docs/` directory, change the file's `out = "docs"` line to a directory of devdocs' own, such as `out = "api-docs"`, before you go on. devdocs replaces a file it did not write only when you pass `--force`: without it, a run refuses when such a file is in its way, and otherwise writes its pages among yours.
|
|
96
|
+
|
|
97
|
+
Price the run, then make it:
|
|
98
|
+
|
|
99
|
+
```sh
|
|
100
|
+
devdocs estimate
|
|
101
|
+
devdocs generate
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`estimate` sends nothing. `generate` sends the provider your file paths and the source of the files it writes prose for, with lines from related files; [SECURITY.md](https://github.com/bgantavya/devDocs/blob/v4/SECURITY.md#generated-documentation-quotes-your-code) says what goes out. It writes the documentation to `docs/`, or to the directory you set in `out`. Start reading at its `README.md`, the home page.
|
|
105
|
+
|
|
106
|
+
For a site you can open in a browser, run `devdocs export --format html` and open `docs/index.html`; `devdocs export --format pdf` makes a PDF book. `export` renders the last run again, with no key and no cost. The next `generate` removes exported files in any format it does not write, since they describe an older run. To keep a format, give it to `generate` too, as in `devdocs generate --format markdown,html`, or set `formats` in `devdocs.toml`.
|
|
107
|
+
|
|
108
|
+
`generate` also creates `.devdocs/` in the project root, which holds every usable answer and the record of each run. Keep it, so later runs reuse those answers, but keep it out of version control. Without a `.gitignore`, or with a `devdocs.toml` you wrote yourself, add the line `.devdocs/` to `.gitignore` by hand: `init --force` would replace your `devdocs.toml`.
|
|
109
|
+
|
|
110
|
+
## A sample run
|
|
111
|
+
|
|
112
|
+
On a small project, a `shop` package of six Python files, with one test file, a `pyproject.toml` and the `devdocs.toml` that `init` wrote, `estimate` prints:
|
|
113
|
+
|
|
114
|
+
```text
|
|
115
|
+
scanned 9 files, 6 documentable, 8 model calls planned (0.0s)
|
|
116
|
+
6 files: 6 with prose, 0 from facts alone
|
|
117
|
+
8 model calls (1 architecture, 6 files, 1 module), 0 already cached
|
|
118
|
+
at most 16,222 input / 3,794 output tokens, at most $0.0214
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`generate` then writes:
|
|
122
|
+
|
|
123
|
+
```text
|
|
124
|
+
docs/
|
|
125
|
+
├── README.md home page
|
|
126
|
+
├── architecture.md architecture overview
|
|
127
|
+
├── index.json manifest: the run's documents and files
|
|
128
|
+
└── shop/
|
|
129
|
+
├── index.md module page
|
|
130
|
+
├── __init__.py.md
|
|
131
|
+
├── cart.py.md
|
|
132
|
+
├── cli.py.md
|
|
133
|
+
├── money.py.md
|
|
134
|
+
├── orders.py.md
|
|
135
|
+
└── tax.py.md
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Each file page gives the facts: the file's module, language and line count, whether it is an entry point, the files and tests that import it, its public symbols with their exact signatures and docstrings, its dependencies, and the TODO, FIXME and similar notes in its comments. Where the plan gives a file prose, the model adds a summary, a sentence for each public name the source leaves undocumented, and notes on behaviour the code does not make obvious.
|
|
139
|
+
|
|
140
|
+
## Costs
|
|
141
|
+
|
|
142
|
+
- By default, file pages get their prose from the provider's cheapest models, such as `gemini-2.5-flash-lite` or `claude-haiku-5-5`, and the module summaries and the architecture overview from stronger ones. `--quality balanced` or `high` plans prose for more files and sends more of the work to stronger models, so it costs more. Under the default limit, `high` can end with fewer files with prose than `cheap`; `estimate` shows how many get prose before you pay.
|
|
143
|
+
- Files that need no prose get none. Every usable answer is cached under its prompt, so a run after an edit pays only for the prompts the edit changed: the edited files, files that gained or lost an importer or a test, and the module summaries and the architecture overview above them when what they sum up has changed.
|
|
144
|
+
- A run is capped at $0.50 by default. A plan whose worst-case price is higher is cut to fit before anything is sent, and what is cut becomes a stub. Set `--max-cost` to change the limit, and `--max-requests` to cap the requests. `--max-cost 0` and `--max-requests 0` mean no limit, not zero spend.
|
|
145
|
+
- `devdocs estimate` prices the plan at its worst case, offline and free. It assumes your key reaches devdocs' first-choice models, and leaves out retries and escalations to stronger models; the limits cap those all the same.
|
|
146
|
+
- By default devdocs keeps to Gemini's free-tier rate limits and models, so a run can pause for up to a minute at a time, printing nothing, while a model's per-minute limit frees up ([troubleshooting.md](https://github.com/bgantavya/devDocs/blob/v4/docs/troubleshooting.md#a-run-pauses-with-no-output)); pass `--paid` with a paid key. Free tier or not, devdocs prices every call at the paid rates in its catalog: it does not read the vendor's bill.
|
|
147
|
+
- Google now serves the 2.5 models only to projects that used them before, so with a key from a new project devdocs uses the 3.x models, which cost more per token than `estimate` assumes. On the free tier such a key reaches no architecture-tier model, so a module-tier model writes the overview, and at `--quality high` every page. The progress lines of `generate` name the model behind each call, and [models.md](https://github.com/bgantavya/devDocs/blob/v4/docs/models.md#gemini-models) explains the routing.
|
|
148
|
+
|
|
149
|
+
[costs.md](https://github.com/bgantavya/devDocs/blob/v4/docs/costs.md) explains what a run costs and how to keep it low.
|
|
150
|
+
|
|
151
|
+
## Commands
|
|
152
|
+
|
|
153
|
+
| Command | What it does |
|
|
154
|
+
|---|---|
|
|
155
|
+
| `devdocs generate [path]` | Write docs for a project. |
|
|
156
|
+
| `devdocs estimate [path]` | Price a run, send nothing. |
|
|
157
|
+
| `devdocs export [path]` | Render the last run again, in other formats; no key, no cost. |
|
|
158
|
+
| `devdocs doctor [path]` | Check that a run can work. |
|
|
159
|
+
| `devdocs init [path]` | Write a starter `devdocs.toml`. |
|
|
160
|
+
| `devdocs models` | List the models devdocs knows for the provider, their prices, and which your key can use. |
|
|
161
|
+
| `devdocs cache {stats,clear} [path]` | Inspect or clear the response cache. |
|
|
162
|
+
|
|
163
|
+
`devdocs <command> --help` lists a command's options. [commands.md](https://github.com/bgantavya/devDocs/blob/v4/docs/commands.md) documents every flag and exit code.
|
|
164
|
+
|
|
165
|
+
## Configuration
|
|
166
|
+
|
|
167
|
+
Settings come from flags, `DEVDOCS_*` environment variables and a `devdocs.toml` file, in that order of precedence. A minimal file, in the project root:
|
|
168
|
+
|
|
169
|
+
```toml
|
|
170
|
+
[devdocs]
|
|
171
|
+
path = "." # the project root: this file's directory
|
|
172
|
+
out = "docs" # where the docs go, under the project root
|
|
173
|
+
provider = "gemini"
|
|
174
|
+
quality = "cheap"
|
|
175
|
+
max_cost = 0.50 # USD per run; 0 means no limit, not zero spend
|
|
176
|
+
formats = ["markdown", "html"]
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
With `path = "."`, devdocs documents the whole project from any directory in it; without `path`, the project is the directory you run devdocs in. `devdocs init` writes a commented starter file, without `path`. [configuration.md](https://github.com/bgantavya/devDocs/blob/v4/docs/configuration.md) lists every setting.
|
|
180
|
+
|
|
181
|
+
## CI, Docker and upgrading
|
|
182
|
+
|
|
183
|
+
- **CI:** devdocs runs unattended, with its key from a secret, a budget and a cached `.devdocs/`, so a re-run reuses the answers already bought. See [ci.md](https://github.com/bgantavya/devDocs/blob/v4/docs/ci.md).
|
|
184
|
+
- **Docker:** `docker run --rm -it -u "$(id -u):$(id -g)" -v "$PWD:/work" -e GEMINI_API_KEY ghcr.io/bgantavya/devdocs:4.0.0 generate` documents the current directory. See [the install guide](https://github.com/bgantavya/devDocs/blob/v4/docs/install.md#docker).
|
|
185
|
+
- **From 3.x:** version 4 is a rewrite, and its command is `devdocs`, in lower case. Uninstall 3.x first: on macOS and Windows its `devDocs` command can answer for `devdocs`. A 3.x command line that uses a flag only 3.x had, such as `-p` or `--output`, still runs, translated, with a notice; a bare `devdocs` prints the help. See [migration.md](https://github.com/bgantavya/devDocs/blob/v4/docs/migration.md).
|
|
186
|
+
|
|
187
|
+
## Documentation
|
|
188
|
+
|
|
189
|
+
[The documentation index](https://github.com/bgantavya/devDocs/blob/v4/docs/README.md) lists every page with the question it answers.
|
|
190
|
+
|
|
191
|
+
- [Install](https://github.com/bgantavya/devDocs/blob/v4/docs/install.md): every way to install, upgrade and remove devdocs.
|
|
192
|
+
- [Commands](https://github.com/bgantavya/devDocs/blob/v4/docs/commands.md): every command, flag and exit code, and how a run stops.
|
|
193
|
+
- [Configuration](https://github.com/bgantavya/devDocs/blob/v4/docs/configuration.md): `devdocs.toml`, environment variables and the API key.
|
|
194
|
+
- [Models](https://github.com/bgantavya/devDocs/blob/v4/docs/models.md): providers, keys and how models are chosen.
|
|
195
|
+
- [Costs](https://github.com/bgantavya/devDocs/blob/v4/docs/costs.md): what a run costs, the budget, and `estimate`.
|
|
196
|
+
- [Context](https://github.com/bgantavya/devDocs/blob/v4/docs/context.md): the cross-file context each prompt gets.
|
|
197
|
+
- [Output](https://github.com/bgantavya/devDocs/blob/v4/docs/output.md): what a run writes, the formats, the files devdocs never replaces, and `export`.
|
|
198
|
+
- [Troubleshooting](https://github.com/bgantavya/devDocs/blob/v4/docs/troubleshooting.md): `doctor`, then problems and fixes.
|
|
199
|
+
- [Migration](https://github.com/bgantavya/devDocs/blob/v4/docs/migration.md): moving from 3.x.
|
|
200
|
+
- [CI](https://github.com/bgantavya/devDocs/blob/v4/docs/ci.md): unattended runs, GitHub Actions and Docker.
|
|
201
|
+
- [Architecture](https://github.com/bgantavya/devDocs/blob/v4/docs/architecture.md): how devdocs works inside, for contributors.
|
|
202
|
+
- [Changelog](https://github.com/bgantavya/devDocs/blob/v4/CHANGELOG.md): what changed in each release.
|
|
203
|
+
|
|
204
|
+
## Contributing, security and license
|
|
205
|
+
|
|
206
|
+
- [CONTRIBUTING.md](https://github.com/bgantavya/devDocs/blob/v4/CONTRIBUTING.md) covers the development setup, the checks a change must pass, and how to send a pull request.
|
|
207
|
+
- [SECURITY.md](https://github.com/bgantavya/devDocs/blob/v4/SECURITY.md) says what devdocs sends to the provider, and how to report a vulnerability.
|
|
208
|
+
- Everyone taking part follows the [code of conduct](https://github.com/bgantavya/devDocs/blob/v4/CODE_OF_CONDUCT.md).
|
|
209
|
+
- devdocs is released under the [MIT License](https://github.com/bgantavya/devDocs/blob/v4/LICENSE).
|
|
210
|
+
- Report a bug, a wrong generated page or a feature request in [the issue tracker](https://github.com/bgantavya/devDocs/issues).
|
devdocs-4.0.0/README.md
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
# devdocs
|
|
2
|
+
|
|
3
|
+
Documentation from source code: exact facts from parsers, model prose only where it adds something, on a hard budget. No dependencies.
|
|
4
|
+
|
|
5
|
+
[](https://github.com/bgantavya/devDocs/actions/workflows/publish.yml?query=branch%3Av4)
|
|
6
|
+
[](https://pypi.org/project/devDocs/)
|
|
7
|
+
[](https://pypi.org/project/devDocs/)
|
|
8
|
+
[](https://github.com/bgantavya/devDocs/blob/v4/LICENSE)
|
|
9
|
+
|
|
10
|
+
devdocs is a command-line tool that writes the documentation of a code base: an overview of the architecture, a page for each module (each directory of source files), and a page for each source file other than tests and vendored or generated code. Parsers supply the facts. A model, Google Gemini or Anthropic Claude, writes prose only where it adds something, within a hard budget.
|
|
11
|
+
|
|
12
|
+
## Why devdocs
|
|
13
|
+
|
|
14
|
+
- **Facts come from parsers.** Parsers for Python, JavaScript, TypeScript, Go, Rust and Java read each file's public symbols, signatures, docstrings and imports, and the pages print signatures as the source writes them. The model writes prose around these facts; it never supplies them.
|
|
15
|
+
- **Prose only where it adds something.** devdocs ranks the files and gives prose to those where it adds most. A file its own docstrings already document, or one that ranks low, gets a page from facts alone, called a stub, at no cost. `devdocs estimate --explain` shows each file's plan and the reason for it.
|
|
16
|
+
- **A hard budget, priced first.** A run spends at most $0.50 unless you set another limit; a limit of 0 means no limit, not zero spend. Each request reserves its worst-case price before it is sent, so a run stays within the limit, and `devdocs estimate` prices a run before you pay for anything.
|
|
17
|
+
- **Cached and resumable.** Every usable answer is kept in `.devdocs/` in the project, and reused for free while its prompt and model stay the same ([costs.md](https://github.com/bgantavya/devDocs/blob/v4/docs/costs.md#what-a-re-run-pays-for)). A stopped run resumes where it stopped.
|
|
18
|
+
- **Markdown, HTML and PDF.** Markdown pages, a static HTML site that needs no server, and PDF from a built-in engine, or from an installed Chrome, Chromium, Edge or WeasyPrint for all of Unicode.
|
|
19
|
+
- **Gemini or Claude.** Gemini is the default; Claude is one setting away.
|
|
20
|
+
- **No dependencies.** Python 3.11 or newer and its standard library, nothing else. devdocs also installs from npm, and runs as a container image.
|
|
21
|
+
|
|
22
|
+
## Quick start
|
|
23
|
+
|
|
24
|
+
Install devdocs with [pipx](https://pipx.pypa.io/):
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
pipx install "devDocs>=4"
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
devdocs needs Python 3.11 or newer. If pipx runs on an older Python, name a newer one, as in `pipx install --python python3.13 "devDocs>=4"`. If you have no Python 3.11 or newer, [uv](https://docs.astral.sh/uv/) downloads one as it installs devdocs: `uv tool install --python 3.13 "devDocs>=4"`. [The install guide](https://github.com/bgantavya/devDocs/blob/v4/docs/install.md) covers every method, and upgrading and removing.
|
|
31
|
+
|
|
32
|
+
Check the setup with `devdocs doctor --offline`. It sends nothing, and marks the API key `!!` until you set one.
|
|
33
|
+
|
|
34
|
+
Get an API key from [Google AI Studio](https://aistudio.google.com/apikey) for Gemini, or from the [Anthropic Console](https://console.anthropic.com/) for Claude. In bash or zsh, run the line for your provider, paste the key and press Enter. `read -s` keeps the key off the screen and out of your shell history.
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
read -rs GEMINI_API_KEY && export GEMINI_API_KEY
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
For Claude, the line also selects the provider:
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY DEVDOCS_PROVIDER=anthropic
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
In PowerShell, use `$env:GEMINI_API_KEY = 'your-key'`, or for Claude `$env:ANTHROPIC_API_KEY = 'your-key'; $env:DEVDOCS_PROVIDER = 'anthropic'`, with your key in place of `your-key`.
|
|
47
|
+
|
|
48
|
+
Then, at the root of your project, write a starter `devdocs.toml`:
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
devdocs init
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
For Claude, run `devdocs init --provider anthropic` instead, so the file selects Claude too. `init` also adds `.devdocs/`, where devdocs keeps what it buys, to your `.gitignore`; it creates no `.gitignore` if you have none.
|
|
55
|
+
|
|
56
|
+
If your project already has a `docs/` directory, change the file's `out = "docs"` line to a directory of devdocs' own, such as `out = "api-docs"`, before you go on. devdocs replaces a file it did not write only when you pass `--force`: without it, a run refuses when such a file is in its way, and otherwise writes its pages among yours.
|
|
57
|
+
|
|
58
|
+
Price the run, then make it:
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
devdocs estimate
|
|
62
|
+
devdocs generate
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`estimate` sends nothing. `generate` sends the provider your file paths and the source of the files it writes prose for, with lines from related files; [SECURITY.md](https://github.com/bgantavya/devDocs/blob/v4/SECURITY.md#generated-documentation-quotes-your-code) says what goes out. It writes the documentation to `docs/`, or to the directory you set in `out`. Start reading at its `README.md`, the home page.
|
|
66
|
+
|
|
67
|
+
For a site you can open in a browser, run `devdocs export --format html` and open `docs/index.html`; `devdocs export --format pdf` makes a PDF book. `export` renders the last run again, with no key and no cost. The next `generate` removes exported files in any format it does not write, since they describe an older run. To keep a format, give it to `generate` too, as in `devdocs generate --format markdown,html`, or set `formats` in `devdocs.toml`.
|
|
68
|
+
|
|
69
|
+
`generate` also creates `.devdocs/` in the project root, which holds every usable answer and the record of each run. Keep it, so later runs reuse those answers, but keep it out of version control. Without a `.gitignore`, or with a `devdocs.toml` you wrote yourself, add the line `.devdocs/` to `.gitignore` by hand: `init --force` would replace your `devdocs.toml`.
|
|
70
|
+
|
|
71
|
+
## A sample run
|
|
72
|
+
|
|
73
|
+
On a small project, a `shop` package of six Python files, with one test file, a `pyproject.toml` and the `devdocs.toml` that `init` wrote, `estimate` prints:
|
|
74
|
+
|
|
75
|
+
```text
|
|
76
|
+
scanned 9 files, 6 documentable, 8 model calls planned (0.0s)
|
|
77
|
+
6 files: 6 with prose, 0 from facts alone
|
|
78
|
+
8 model calls (1 architecture, 6 files, 1 module), 0 already cached
|
|
79
|
+
at most 16,222 input / 3,794 output tokens, at most $0.0214
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`generate` then writes:
|
|
83
|
+
|
|
84
|
+
```text
|
|
85
|
+
docs/
|
|
86
|
+
├── README.md home page
|
|
87
|
+
├── architecture.md architecture overview
|
|
88
|
+
├── index.json manifest: the run's documents and files
|
|
89
|
+
└── shop/
|
|
90
|
+
├── index.md module page
|
|
91
|
+
├── __init__.py.md
|
|
92
|
+
├── cart.py.md
|
|
93
|
+
├── cli.py.md
|
|
94
|
+
├── money.py.md
|
|
95
|
+
├── orders.py.md
|
|
96
|
+
└── tax.py.md
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Each file page gives the facts: the file's module, language and line count, whether it is an entry point, the files and tests that import it, its public symbols with their exact signatures and docstrings, its dependencies, and the TODO, FIXME and similar notes in its comments. Where the plan gives a file prose, the model adds a summary, a sentence for each public name the source leaves undocumented, and notes on behaviour the code does not make obvious.
|
|
100
|
+
|
|
101
|
+
## Costs
|
|
102
|
+
|
|
103
|
+
- By default, file pages get their prose from the provider's cheapest models, such as `gemini-2.5-flash-lite` or `claude-haiku-5-5`, and the module summaries and the architecture overview from stronger ones. `--quality balanced` or `high` plans prose for more files and sends more of the work to stronger models, so it costs more. Under the default limit, `high` can end with fewer files with prose than `cheap`; `estimate` shows how many get prose before you pay.
|
|
104
|
+
- Files that need no prose get none. Every usable answer is cached under its prompt, so a run after an edit pays only for the prompts the edit changed: the edited files, files that gained or lost an importer or a test, and the module summaries and the architecture overview above them when what they sum up has changed.
|
|
105
|
+
- A run is capped at $0.50 by default. A plan whose worst-case price is higher is cut to fit before anything is sent, and what is cut becomes a stub. Set `--max-cost` to change the limit, and `--max-requests` to cap the requests. `--max-cost 0` and `--max-requests 0` mean no limit, not zero spend.
|
|
106
|
+
- `devdocs estimate` prices the plan at its worst case, offline and free. It assumes your key reaches devdocs' first-choice models, and leaves out retries and escalations to stronger models; the limits cap those all the same.
|
|
107
|
+
- By default devdocs keeps to Gemini's free-tier rate limits and models, so a run can pause for up to a minute at a time, printing nothing, while a model's per-minute limit frees up ([troubleshooting.md](https://github.com/bgantavya/devDocs/blob/v4/docs/troubleshooting.md#a-run-pauses-with-no-output)); pass `--paid` with a paid key. Free tier or not, devdocs prices every call at the paid rates in its catalog: it does not read the vendor's bill.
|
|
108
|
+
- Google now serves the 2.5 models only to projects that used them before, so with a key from a new project devdocs uses the 3.x models, which cost more per token than `estimate` assumes. On the free tier such a key reaches no architecture-tier model, so a module-tier model writes the overview, and at `--quality high` every page. The progress lines of `generate` name the model behind each call, and [models.md](https://github.com/bgantavya/devDocs/blob/v4/docs/models.md#gemini-models) explains the routing.
|
|
109
|
+
|
|
110
|
+
[costs.md](https://github.com/bgantavya/devDocs/blob/v4/docs/costs.md) explains what a run costs and how to keep it low.
|
|
111
|
+
|
|
112
|
+
## Commands
|
|
113
|
+
|
|
114
|
+
| Command | What it does |
|
|
115
|
+
|---|---|
|
|
116
|
+
| `devdocs generate [path]` | Write docs for a project. |
|
|
117
|
+
| `devdocs estimate [path]` | Price a run, send nothing. |
|
|
118
|
+
| `devdocs export [path]` | Render the last run again, in other formats; no key, no cost. |
|
|
119
|
+
| `devdocs doctor [path]` | Check that a run can work. |
|
|
120
|
+
| `devdocs init [path]` | Write a starter `devdocs.toml`. |
|
|
121
|
+
| `devdocs models` | List the models devdocs knows for the provider, their prices, and which your key can use. |
|
|
122
|
+
| `devdocs cache {stats,clear} [path]` | Inspect or clear the response cache. |
|
|
123
|
+
|
|
124
|
+
`devdocs <command> --help` lists a command's options. [commands.md](https://github.com/bgantavya/devDocs/blob/v4/docs/commands.md) documents every flag and exit code.
|
|
125
|
+
|
|
126
|
+
## Configuration
|
|
127
|
+
|
|
128
|
+
Settings come from flags, `DEVDOCS_*` environment variables and a `devdocs.toml` file, in that order of precedence. A minimal file, in the project root:
|
|
129
|
+
|
|
130
|
+
```toml
|
|
131
|
+
[devdocs]
|
|
132
|
+
path = "." # the project root: this file's directory
|
|
133
|
+
out = "docs" # where the docs go, under the project root
|
|
134
|
+
provider = "gemini"
|
|
135
|
+
quality = "cheap"
|
|
136
|
+
max_cost = 0.50 # USD per run; 0 means no limit, not zero spend
|
|
137
|
+
formats = ["markdown", "html"]
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
With `path = "."`, devdocs documents the whole project from any directory in it; without `path`, the project is the directory you run devdocs in. `devdocs init` writes a commented starter file, without `path`. [configuration.md](https://github.com/bgantavya/devDocs/blob/v4/docs/configuration.md) lists every setting.
|
|
141
|
+
|
|
142
|
+
## CI, Docker and upgrading
|
|
143
|
+
|
|
144
|
+
- **CI:** devdocs runs unattended, with its key from a secret, a budget and a cached `.devdocs/`, so a re-run reuses the answers already bought. See [ci.md](https://github.com/bgantavya/devDocs/blob/v4/docs/ci.md).
|
|
145
|
+
- **Docker:** `docker run --rm -it -u "$(id -u):$(id -g)" -v "$PWD:/work" -e GEMINI_API_KEY ghcr.io/bgantavya/devdocs:4.0.0 generate` documents the current directory. See [the install guide](https://github.com/bgantavya/devDocs/blob/v4/docs/install.md#docker).
|
|
146
|
+
- **From 3.x:** version 4 is a rewrite, and its command is `devdocs`, in lower case. Uninstall 3.x first: on macOS and Windows its `devDocs` command can answer for `devdocs`. A 3.x command line that uses a flag only 3.x had, such as `-p` or `--output`, still runs, translated, with a notice; a bare `devdocs` prints the help. See [migration.md](https://github.com/bgantavya/devDocs/blob/v4/docs/migration.md).
|
|
147
|
+
|
|
148
|
+
## Documentation
|
|
149
|
+
|
|
150
|
+
[The documentation index](https://github.com/bgantavya/devDocs/blob/v4/docs/README.md) lists every page with the question it answers.
|
|
151
|
+
|
|
152
|
+
- [Install](https://github.com/bgantavya/devDocs/blob/v4/docs/install.md): every way to install, upgrade and remove devdocs.
|
|
153
|
+
- [Commands](https://github.com/bgantavya/devDocs/blob/v4/docs/commands.md): every command, flag and exit code, and how a run stops.
|
|
154
|
+
- [Configuration](https://github.com/bgantavya/devDocs/blob/v4/docs/configuration.md): `devdocs.toml`, environment variables and the API key.
|
|
155
|
+
- [Models](https://github.com/bgantavya/devDocs/blob/v4/docs/models.md): providers, keys and how models are chosen.
|
|
156
|
+
- [Costs](https://github.com/bgantavya/devDocs/blob/v4/docs/costs.md): what a run costs, the budget, and `estimate`.
|
|
157
|
+
- [Context](https://github.com/bgantavya/devDocs/blob/v4/docs/context.md): the cross-file context each prompt gets.
|
|
158
|
+
- [Output](https://github.com/bgantavya/devDocs/blob/v4/docs/output.md): what a run writes, the formats, the files devdocs never replaces, and `export`.
|
|
159
|
+
- [Troubleshooting](https://github.com/bgantavya/devDocs/blob/v4/docs/troubleshooting.md): `doctor`, then problems and fixes.
|
|
160
|
+
- [Migration](https://github.com/bgantavya/devDocs/blob/v4/docs/migration.md): moving from 3.x.
|
|
161
|
+
- [CI](https://github.com/bgantavya/devDocs/blob/v4/docs/ci.md): unattended runs, GitHub Actions and Docker.
|
|
162
|
+
- [Architecture](https://github.com/bgantavya/devDocs/blob/v4/docs/architecture.md): how devdocs works inside, for contributors.
|
|
163
|
+
- [Changelog](https://github.com/bgantavya/devDocs/blob/v4/CHANGELOG.md): what changed in each release.
|
|
164
|
+
|
|
165
|
+
## Contributing, security and license
|
|
166
|
+
|
|
167
|
+
- [CONTRIBUTING.md](https://github.com/bgantavya/devDocs/blob/v4/CONTRIBUTING.md) covers the development setup, the checks a change must pass, and how to send a pull request.
|
|
168
|
+
- [SECURITY.md](https://github.com/bgantavya/devDocs/blob/v4/SECURITY.md) says what devdocs sends to the provider, and how to report a vulnerability.
|
|
169
|
+
- Everyone taking part follows the [code of conduct](https://github.com/bgantavya/devDocs/blob/v4/CODE_OF_CONDUCT.md).
|
|
170
|
+
- devdocs is released under the [MIT License](https://github.com/bgantavya/devDocs/blob/v4/LICENSE).
|
|
171
|
+
- Report a bug, a wrong generated page or a feature request in [the issue tracker](https://github.com/bgantavya/devDocs/issues).
|
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: devDocs
|
|
3
|
+
Version: 4.0.0
|
|
4
|
+
Summary: Documentation from source code: exact facts from parsers, model prose only where it adds something, on a hard budget. No dependencies.
|
|
5
|
+
Author-email: Gantavya Bansal <gantavyaoo@gmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/bgantavya/devDocs
|
|
8
|
+
Project-URL: Repository, https://github.com/bgantavya/devDocs
|
|
9
|
+
Project-URL: Issues, https://github.com/bgantavya/devDocs/issues
|
|
10
|
+
Project-URL: Documentation, https://github.com/bgantavya/devDocs/tree/v4/docs
|
|
11
|
+
Keywords: cli,documentation,docs-generator,llm,gemini,claude,markdown,static-analysis,code-documentation,zero-dependency
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: Information Technology
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
24
|
+
Classifier: Topic :: Documentation
|
|
25
|
+
Classifier: Topic :: Software Development :: Documentation
|
|
26
|
+
Classifier: Typing :: Typed
|
|
27
|
+
Requires-Python: >=3.11
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
License-File: LICENSE
|
|
30
|
+
Provides-Extra: anthropic
|
|
31
|
+
Requires-Dist: anthropic>=1.0; extra == "anthropic"
|
|
32
|
+
Provides-Extra: dev
|
|
33
|
+
Requires-Dist: ruff>=0.16; extra == "dev"
|
|
34
|
+
Requires-Dist: mypy>=1.19; extra == "dev"
|
|
35
|
+
Requires-Dist: bandit>=1.8; extra == "dev"
|
|
36
|
+
Requires-Dist: pip-audit>=2.9; extra == "dev"
|
|
37
|
+
Requires-Dist: coverage>=7.10; extra == "dev"
|
|
38
|
+
Dynamic: license-file
|
|
39
|
+
|
|
40
|
+
# devdocs
|
|
41
|
+
|
|
42
|
+
Documentation from source code: exact facts from parsers, model prose only where it adds something, on a hard budget. No dependencies.
|
|
43
|
+
|
|
44
|
+
[](https://github.com/bgantavya/devDocs/actions/workflows/publish.yml?query=branch%3Av4)
|
|
45
|
+
[](https://pypi.org/project/devDocs/)
|
|
46
|
+
[](https://pypi.org/project/devDocs/)
|
|
47
|
+
[](https://github.com/bgantavya/devDocs/blob/v4/LICENSE)
|
|
48
|
+
|
|
49
|
+
devdocs is a command-line tool that writes the documentation of a code base: an overview of the architecture, a page for each module (each directory of source files), and a page for each source file other than tests and vendored or generated code. Parsers supply the facts. A model, Google Gemini or Anthropic Claude, writes prose only where it adds something, within a hard budget.
|
|
50
|
+
|
|
51
|
+
## Why devdocs
|
|
52
|
+
|
|
53
|
+
- **Facts come from parsers.** Parsers for Python, JavaScript, TypeScript, Go, Rust and Java read each file's public symbols, signatures, docstrings and imports, and the pages print signatures as the source writes them. The model writes prose around these facts; it never supplies them.
|
|
54
|
+
- **Prose only where it adds something.** devdocs ranks the files and gives prose to those where it adds most. A file its own docstrings already document, or one that ranks low, gets a page from facts alone, called a stub, at no cost. `devdocs estimate --explain` shows each file's plan and the reason for it.
|
|
55
|
+
- **A hard budget, priced first.** A run spends at most $0.50 unless you set another limit; a limit of 0 means no limit, not zero spend. Each request reserves its worst-case price before it is sent, so a run stays within the limit, and `devdocs estimate` prices a run before you pay for anything.
|
|
56
|
+
- **Cached and resumable.** Every usable answer is kept in `.devdocs/` in the project, and reused for free while its prompt and model stay the same ([costs.md](https://github.com/bgantavya/devDocs/blob/v4/docs/costs.md#what-a-re-run-pays-for)). A stopped run resumes where it stopped.
|
|
57
|
+
- **Markdown, HTML and PDF.** Markdown pages, a static HTML site that needs no server, and PDF from a built-in engine, or from an installed Chrome, Chromium, Edge or WeasyPrint for all of Unicode.
|
|
58
|
+
- **Gemini or Claude.** Gemini is the default; Claude is one setting away.
|
|
59
|
+
- **No dependencies.** Python 3.11 or newer and its standard library, nothing else. devdocs also installs from npm, and runs as a container image.
|
|
60
|
+
|
|
61
|
+
## Quick start
|
|
62
|
+
|
|
63
|
+
Install devdocs with [pipx](https://pipx.pypa.io/):
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
pipx install "devDocs>=4"
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
devdocs needs Python 3.11 or newer. If pipx runs on an older Python, name a newer one, as in `pipx install --python python3.13 "devDocs>=4"`. If you have no Python 3.11 or newer, [uv](https://docs.astral.sh/uv/) downloads one as it installs devdocs: `uv tool install --python 3.13 "devDocs>=4"`. [The install guide](https://github.com/bgantavya/devDocs/blob/v4/docs/install.md) covers every method, and upgrading and removing.
|
|
70
|
+
|
|
71
|
+
Check the setup with `devdocs doctor --offline`. It sends nothing, and marks the API key `!!` until you set one.
|
|
72
|
+
|
|
73
|
+
Get an API key from [Google AI Studio](https://aistudio.google.com/apikey) for Gemini, or from the [Anthropic Console](https://console.anthropic.com/) for Claude. In bash or zsh, run the line for your provider, paste the key and press Enter. `read -s` keeps the key off the screen and out of your shell history.
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
read -rs GEMINI_API_KEY && export GEMINI_API_KEY
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
For Claude, the line also selects the provider:
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY DEVDOCS_PROVIDER=anthropic
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
In PowerShell, use `$env:GEMINI_API_KEY = 'your-key'`, or for Claude `$env:ANTHROPIC_API_KEY = 'your-key'; $env:DEVDOCS_PROVIDER = 'anthropic'`, with your key in place of `your-key`.
|
|
86
|
+
|
|
87
|
+
Then, at the root of your project, write a starter `devdocs.toml`:
|
|
88
|
+
|
|
89
|
+
```sh
|
|
90
|
+
devdocs init
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
For Claude, run `devdocs init --provider anthropic` instead, so the file selects Claude too. `init` also adds `.devdocs/`, where devdocs keeps what it buys, to your `.gitignore`; it creates no `.gitignore` if you have none.
|
|
94
|
+
|
|
95
|
+
If your project already has a `docs/` directory, change the file's `out = "docs"` line to a directory of devdocs' own, such as `out = "api-docs"`, before you go on. devdocs replaces a file it did not write only when you pass `--force`: without it, a run refuses when such a file is in its way, and otherwise writes its pages among yours.
|
|
96
|
+
|
|
97
|
+
Price the run, then make it:
|
|
98
|
+
|
|
99
|
+
```sh
|
|
100
|
+
devdocs estimate
|
|
101
|
+
devdocs generate
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`estimate` sends nothing. `generate` sends the provider your file paths and the source of the files it writes prose for, with lines from related files; [SECURITY.md](https://github.com/bgantavya/devDocs/blob/v4/SECURITY.md#generated-documentation-quotes-your-code) says what goes out. It writes the documentation to `docs/`, or to the directory you set in `out`. Start reading at its `README.md`, the home page.
|
|
105
|
+
|
|
106
|
+
For a site you can open in a browser, run `devdocs export --format html` and open `docs/index.html`; `devdocs export --format pdf` makes a PDF book. `export` renders the last run again, with no key and no cost. The next `generate` removes exported files in any format it does not write, since they describe an older run. To keep a format, give it to `generate` too, as in `devdocs generate --format markdown,html`, or set `formats` in `devdocs.toml`.
|
|
107
|
+
|
|
108
|
+
`generate` also creates `.devdocs/` in the project root, which holds every usable answer and the record of each run. Keep it, so later runs reuse those answers, but keep it out of version control. Without a `.gitignore`, or with a `devdocs.toml` you wrote yourself, add the line `.devdocs/` to `.gitignore` by hand: `init --force` would replace your `devdocs.toml`.
|
|
109
|
+
|
|
110
|
+
## A sample run
|
|
111
|
+
|
|
112
|
+
On a small project, a `shop` package of six Python files, with one test file, a `pyproject.toml` and the `devdocs.toml` that `init` wrote, `estimate` prints:
|
|
113
|
+
|
|
114
|
+
```text
|
|
115
|
+
scanned 9 files, 6 documentable, 8 model calls planned (0.0s)
|
|
116
|
+
6 files: 6 with prose, 0 from facts alone
|
|
117
|
+
8 model calls (1 architecture, 6 files, 1 module), 0 already cached
|
|
118
|
+
at most 16,222 input / 3,794 output tokens, at most $0.0214
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`generate` then writes:
|
|
122
|
+
|
|
123
|
+
```text
|
|
124
|
+
docs/
|
|
125
|
+
├── README.md home page
|
|
126
|
+
├── architecture.md architecture overview
|
|
127
|
+
├── index.json manifest: the run's documents and files
|
|
128
|
+
└── shop/
|
|
129
|
+
├── index.md module page
|
|
130
|
+
├── __init__.py.md
|
|
131
|
+
├── cart.py.md
|
|
132
|
+
├── cli.py.md
|
|
133
|
+
├── money.py.md
|
|
134
|
+
├── orders.py.md
|
|
135
|
+
└── tax.py.md
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Each file page gives the facts: the file's module, language and line count, whether it is an entry point, the files and tests that import it, its public symbols with their exact signatures and docstrings, its dependencies, and the TODO, FIXME and similar notes in its comments. Where the plan gives a file prose, the model adds a summary, a sentence for each public name the source leaves undocumented, and notes on behaviour the code does not make obvious.
|
|
139
|
+
|
|
140
|
+
## Costs
|
|
141
|
+
|
|
142
|
+
- By default, file pages get their prose from the provider's cheapest models, such as `gemini-2.5-flash-lite` or `claude-haiku-5-5`, and the module summaries and the architecture overview from stronger ones. `--quality balanced` or `high` plans prose for more files and sends more of the work to stronger models, so it costs more. Under the default limit, `high` can end with fewer files with prose than `cheap`; `estimate` shows how many get prose before you pay.
|
|
143
|
+
- Files that need no prose get none. Every usable answer is cached under its prompt, so a run after an edit pays only for the prompts the edit changed: the edited files, files that gained or lost an importer or a test, and the module summaries and the architecture overview above them when what they sum up has changed.
|
|
144
|
+
- A run is capped at $0.50 by default. A plan whose worst-case price is higher is cut to fit before anything is sent, and what is cut becomes a stub. Set `--max-cost` to change the limit, and `--max-requests` to cap the requests. `--max-cost 0` and `--max-requests 0` mean no limit, not zero spend.
|
|
145
|
+
- `devdocs estimate` prices the plan at its worst case, offline and free. It assumes your key reaches devdocs' first-choice models, and leaves out retries and escalations to stronger models; the limits cap those all the same.
|
|
146
|
+
- By default devdocs keeps to Gemini's free-tier rate limits and models, so a run can pause for up to a minute at a time, printing nothing, while a model's per-minute limit frees up ([troubleshooting.md](https://github.com/bgantavya/devDocs/blob/v4/docs/troubleshooting.md#a-run-pauses-with-no-output)); pass `--paid` with a paid key. Free tier or not, devdocs prices every call at the paid rates in its catalog: it does not read the vendor's bill.
|
|
147
|
+
- Google now serves the 2.5 models only to projects that used them before, so with a key from a new project devdocs uses the 3.x models, which cost more per token than `estimate` assumes. On the free tier such a key reaches no architecture-tier model, so a module-tier model writes the overview, and at `--quality high` every page. The progress lines of `generate` name the model behind each call, and [models.md](https://github.com/bgantavya/devDocs/blob/v4/docs/models.md#gemini-models) explains the routing.
|
|
148
|
+
|
|
149
|
+
[costs.md](https://github.com/bgantavya/devDocs/blob/v4/docs/costs.md) explains what a run costs and how to keep it low.
|
|
150
|
+
|
|
151
|
+
## Commands
|
|
152
|
+
|
|
153
|
+
| Command | What it does |
|
|
154
|
+
|---|---|
|
|
155
|
+
| `devdocs generate [path]` | Write docs for a project. |
|
|
156
|
+
| `devdocs estimate [path]` | Price a run, send nothing. |
|
|
157
|
+
| `devdocs export [path]` | Render the last run again, in other formats; no key, no cost. |
|
|
158
|
+
| `devdocs doctor [path]` | Check that a run can work. |
|
|
159
|
+
| `devdocs init [path]` | Write a starter `devdocs.toml`. |
|
|
160
|
+
| `devdocs models` | List the models devdocs knows for the provider, their prices, and which your key can use. |
|
|
161
|
+
| `devdocs cache {stats,clear} [path]` | Inspect or clear the response cache. |
|
|
162
|
+
|
|
163
|
+
`devdocs <command> --help` lists a command's options. [commands.md](https://github.com/bgantavya/devDocs/blob/v4/docs/commands.md) documents every flag and exit code.
|
|
164
|
+
|
|
165
|
+
## Configuration
|
|
166
|
+
|
|
167
|
+
Settings come from flags, `DEVDOCS_*` environment variables and a `devdocs.toml` file, in that order of precedence. A minimal file, in the project root:
|
|
168
|
+
|
|
169
|
+
```toml
|
|
170
|
+
[devdocs]
|
|
171
|
+
path = "." # the project root: this file's directory
|
|
172
|
+
out = "docs" # where the docs go, under the project root
|
|
173
|
+
provider = "gemini"
|
|
174
|
+
quality = "cheap"
|
|
175
|
+
max_cost = 0.50 # USD per run; 0 means no limit, not zero spend
|
|
176
|
+
formats = ["markdown", "html"]
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
With `path = "."`, devdocs documents the whole project from any directory in it; without `path`, the project is the directory you run devdocs in. `devdocs init` writes a commented starter file, without `path`. [configuration.md](https://github.com/bgantavya/devDocs/blob/v4/docs/configuration.md) lists every setting.
|
|
180
|
+
|
|
181
|
+
## CI, Docker and upgrading
|
|
182
|
+
|
|
183
|
+
- **CI:** devdocs runs unattended, with its key from a secret, a budget and a cached `.devdocs/`, so a re-run reuses the answers already bought. See [ci.md](https://github.com/bgantavya/devDocs/blob/v4/docs/ci.md).
|
|
184
|
+
- **Docker:** `docker run --rm -it -u "$(id -u):$(id -g)" -v "$PWD:/work" -e GEMINI_API_KEY ghcr.io/bgantavya/devdocs:4.0.0 generate` documents the current directory. See [the install guide](https://github.com/bgantavya/devDocs/blob/v4/docs/install.md#docker).
|
|
185
|
+
- **From 3.x:** version 4 is a rewrite, and its command is `devdocs`, in lower case. Uninstall 3.x first: on macOS and Windows its `devDocs` command can answer for `devdocs`. A 3.x command line that uses a flag only 3.x had, such as `-p` or `--output`, still runs, translated, with a notice; a bare `devdocs` prints the help. See [migration.md](https://github.com/bgantavya/devDocs/blob/v4/docs/migration.md).
|
|
186
|
+
|
|
187
|
+
## Documentation
|
|
188
|
+
|
|
189
|
+
[The documentation index](https://github.com/bgantavya/devDocs/blob/v4/docs/README.md) lists every page with the question it answers.
|
|
190
|
+
|
|
191
|
+
- [Install](https://github.com/bgantavya/devDocs/blob/v4/docs/install.md): every way to install, upgrade and remove devdocs.
|
|
192
|
+
- [Commands](https://github.com/bgantavya/devDocs/blob/v4/docs/commands.md): every command, flag and exit code, and how a run stops.
|
|
193
|
+
- [Configuration](https://github.com/bgantavya/devDocs/blob/v4/docs/configuration.md): `devdocs.toml`, environment variables and the API key.
|
|
194
|
+
- [Models](https://github.com/bgantavya/devDocs/blob/v4/docs/models.md): providers, keys and how models are chosen.
|
|
195
|
+
- [Costs](https://github.com/bgantavya/devDocs/blob/v4/docs/costs.md): what a run costs, the budget, and `estimate`.
|
|
196
|
+
- [Context](https://github.com/bgantavya/devDocs/blob/v4/docs/context.md): the cross-file context each prompt gets.
|
|
197
|
+
- [Output](https://github.com/bgantavya/devDocs/blob/v4/docs/output.md): what a run writes, the formats, the files devdocs never replaces, and `export`.
|
|
198
|
+
- [Troubleshooting](https://github.com/bgantavya/devDocs/blob/v4/docs/troubleshooting.md): `doctor`, then problems and fixes.
|
|
199
|
+
- [Migration](https://github.com/bgantavya/devDocs/blob/v4/docs/migration.md): moving from 3.x.
|
|
200
|
+
- [CI](https://github.com/bgantavya/devDocs/blob/v4/docs/ci.md): unattended runs, GitHub Actions and Docker.
|
|
201
|
+
- [Architecture](https://github.com/bgantavya/devDocs/blob/v4/docs/architecture.md): how devdocs works inside, for contributors.
|
|
202
|
+
- [Changelog](https://github.com/bgantavya/devDocs/blob/v4/CHANGELOG.md): what changed in each release.
|
|
203
|
+
|
|
204
|
+
## Contributing, security and license
|
|
205
|
+
|
|
206
|
+
- [CONTRIBUTING.md](https://github.com/bgantavya/devDocs/blob/v4/CONTRIBUTING.md) covers the development setup, the checks a change must pass, and how to send a pull request.
|
|
207
|
+
- [SECURITY.md](https://github.com/bgantavya/devDocs/blob/v4/SECURITY.md) says what devdocs sends to the provider, and how to report a vulnerability.
|
|
208
|
+
- Everyone taking part follows the [code of conduct](https://github.com/bgantavya/devDocs/blob/v4/CODE_OF_CONDUCT.md).
|
|
209
|
+
- devdocs is released under the [MIT License](https://github.com/bgantavya/devDocs/blob/v4/LICENSE).
|
|
210
|
+
- Report a bug, a wrong generated page or a feature request in [the issue tracker](https://github.com/bgantavya/devDocs/issues).
|