doc-code 0.1.0__py3-none-any.whl

doc_code-0.1.0.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: doc-code
+Version: 0.1.0
+Summary: Generate and safely apply AI-assisted source documentation.
+License-Expression: MIT
+Project-URL: Homepage, https://argolo.dev
+Project-URL: Documentation, https://argolo.dev
+Keywords: documentation,docstrings,developer-tools,generative-ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tree-sitter<0.26,>=0.25
+Requires-Dist: tree-sitter-javascript<0.24,>=0.23
+Requires-Dist: tree-sitter-typescript<0.24,>=0.23
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: mypy<2,>=1.11; extra == "dev"
+Requires-Dist: pip-audit<3,>=2.7; extra == "dev"
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: pytest-cov<8,>=5; extra == "dev"
+Requires-Dist: ruff<1,>=0.6; extra == "dev"
+Requires-Dist: commitar<2,>=1.0.0; extra == "dev"
+Requires-Dist: setuptools<84,>=83; extra == "dev"
+Dynamic: license-file
+
+# Doc Code
+
+[Leia em português](README-PTBR.md)
+
+`doc-code` generates documentation for Python, JavaScript, and TypeScript files using OpenAI, Gemini, or Ollama.
+
+By default, it displays a reviewable diff of the generated documentation. Use `--no-show-diff` to keep only the compact summary. To write the changes, run:
+
+```shell
+doc-code --output apply
+```
+
+For automation, combine `--yes` with `--output apply`. Each file is written as soon as its generation and validation complete; a later failure does not roll back files that were already applied. Immediately before writing, the file is compared with the preview. If it changed, `doc-code` does not overwrite it. With `confirm = true`, Doc Code shows and confirms each formatted docstring before applying it; with `confirm = false`, it reviews the complete generated file diff before applying it.
+
+## Installation and requirements
+
+`doc-code` requires Python 3.11 or later and Git on your `PATH`. To process JavaScript, install Node.js. For TypeScript/TSX, also install the `tsc` compiler (for example, `npm install --global typescript`). These executables validate generated syntax before any file is changed.
+
+For development, run `uv sync --locked --all-extras`. To install the published package, run `pip install doc-code`.
+
+## Usage
+
+```shell
+doc-code                         # Git changes: staged, unstaged, and untracked files
+doc-code src/a.py src/b.ts       # one or more specific files or directories
+doc-code --selection repository  # every eligible file
+doc-code --coverage all --format numpy
+doc-code --language Portuguese
+doc-code --request-scope symbol
+doc-code --no-show-diff          # compact preview without the unified diff
+doc-code --check                 # fail CI when symbols are undocumented
+doc-code --continue-on-error     # return status 0 when a file is skipped
+doc-code config init
+doc-code config show
+```
+
+Configuration uses this precedence: flags, `--config`, `DOC_CODE_*` environment variables, `.doc-code.toml`, user configuration, and defaults. Set `language = "Portuguese"` in `[documentation]`, use `DOC_CODE_LANGUAGE`, or pass `--language Portuguese` to control the generated language. Credentials use `OPENAI_API_KEY` or `GEMINI_API_KEY`; Ollama needs no credential.
+
+## Configuration (`.doc-code.toml`)
+
+Create a starter file with `doc-code config init`. The `[ai]`, `[documentation]`, and `[limits]` sections are merged into one configuration. The following are all accepted keys.
+
+### `[ai]`
+
+| Option | Values / default | Purpose |
+| --- | --- | --- |
+| `provider` | `openai`, `gemini`, or `ollama` · `ollama` | Selects the provider that generates descriptions. |
+| `model` | string · provider-dependent | Single model used when `models` is empty: `qwen2.5-coder:14b`, `gpt-5.6-sol`, or `gemini-3.6-flash`. |
+| `models` | list of up to 3 strings · `qwen2.5-coder:14b`, `gemma4:e4b` | Candidates rotated across attempts; takes precedence over `model`. An empty list uses only `model`. |
+| `endpoint` | URL or absent · provider default endpoint | Overrides the provider endpoint. Authenticated providers require HTTPS outside loopback. |
+| `max_input_tokens` | positive integer · `12000` | Estimated limit for the prompt sent to the model. |
+| `context_window_tokens` | positive integer · `32768` | Total model context window; must fit input and output. |
+| `max_output_tokens` | positive integer · `800` | Limit for generated response tokens. |
+| `temperature` | number · `0.2` | Controls variation; must be non-negative and is between 0 and 2 for OpenAI and Gemini. |
+| `timeout_seconds` | positive integer · `60` | Maximum duration of each provider call. |
+
+`max_input_tokens + max_output_tokens` cannot exceed `context_window_tokens`.
+
+### `[documentation]`
+
+| Option | Values / default | Purpose |
+| --- | --- | --- |
+| `selection` | `changes`, `repository` · `changes` | Chooses Git changes or every eligible file. |
+| `coverage` | `missing`, `minimal`, `all` · `missing` | `missing` includes every undocumented symbol; `minimal` includes only undocumented modules and top-level public APIs; `all` generates or replaces documentation for every symbol. |
+| `request_scope` | `file`, `symbol` · `file` | Chooses the context for each call: a complete file or one symbol. It does not change which symbols are eligible. |
+| `language` | non-empty string · `English` | Language requested for generated descriptions. |
+| `python_format` | `google`, `numpy`, `sphinx` · `google` | Parameter-section style for Python docstrings. |
+| `javascript_format` | `jsdoc` · `jsdoc` | Annotation style for JavaScript and TypeScript. |
+| `output` | `preview`, `apply` · `preview` | Shows a preview or writes changes. |
+| `confirm` | boolean · `true` | `true` shows and confirms each formatted docstring before applying it; `false` shows the generated file diff and confirms it before applying it. |
+
+### `[limits]`
+
+| Option | Values / default | Purpose |
+| --- | --- | --- |
+| `max_files_per_request` | positive integer · `50` | Maximum number of files in a scope. |
+| `max_file_bytes` | positive integer · `100000` | Maximum size of each processed file. |
+| `exclude` | list of glob patterns | Removes files from scope. Defaults exclude dependencies, build artifacts, minified files, and `package-lock.json`. |
+| `include` | list of glob patterns · empty list | When provided, keeps only files matching at least one pattern. |
+
+## Python docstring style
+
+Generated Python docstrings follow PEP 257: summaries end in a period; multiline docstrings have a blank line before and after sections, with closing quotes on their own line. Module and class docstrings are separated from the next declaration by one blank line. Empty lines have no indentation whitespace.
+
+Line length also follows the target project. For Python, `doc-code` uses `tool.ruff.line-length` and `tool.ruff.lint.pydocstyle.convention` from the nearest `pyproject.toml` (or 88 and the configured `doc-code` format when absent). Long summaries are separated from the description by a blank line according to D205. For JavaScript and TypeScript, it uses `max-len` from the nearest `eslint.config.js`, `eslint.config.mjs`, or `eslint.config.cjs` (or 100 when no rule exists). Descriptions and JSDoc lines are wrapped while accounting for indentation and delimiters.
+
+The `google`, `numpy`, and `sphinx` styles affect only the parameter section. To rewrite existing docstrings using one of these styles, run:
+
+```shell
+doc-code --coverage all --output apply --yes
+```
+
+For functions and methods, `doc-code` asks the model for a distinct description for every parameter and inserts it in the corresponding parameter section. The structured response must include every requested symbol and parameter; incomplete responses are rejected and generated again. Legacy integrations retain a fallback text for compatibility.
+
+By default, `request_scope = "file"` sends the file and all symbols that require generation in a single request. Use `request_scope = "symbol"` (or `--request-scope symbol`) to send each symbol in a separate request with only its code scope. This reduces context in large files but can increase latency and the number of calls. For modules, it sends a structural index — opening docstring, imports, constants, and public signatures — without bodies. With `output = "apply"` and `confirm = true`, each formatted docstring is reviewed and confirmed individually; a rejected docstring is reported and skipped while the remaining symbols continue. `--yes` applies without prompts. With `confirm = false`, the full file diff is reviewed before any of its changes are written.
+
+Regardless of `request_scope`, `coverage` decides which symbols are eligible and `request_scope` only changes the context unit sent to the model. Use `coverage = "all"` to rewrite existing documentation.
+
+Partial failures return status 1 after all remaining eligible files have been processed. Use `--continue-on-error` only when automation explicitly accepts partial results.

doc_code-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+doc_code/__init__.py,sha256=Le2nLJbYCiQkRHNz_cxOibgIWmVEJIn8kAB614jzJQ8,101
+doc_code/ai.py,sha256=bJWfgSI5jSlPoG3CYBwEKYYFYzD5RPOeE18PjWzC9JE,9026
+doc_code/cli.py,sha256=9ThRu76MrK-GnXvs-5d26pyQB6KzyVNrajQAZjYOIsY,22383
+doc_code/config.py,sha256=1lqkkL1ZtoZ7v683s1eqwjwTpH9zLzde6oATz_fn1Vo,12502
+doc_code/editor.py,sha256=xPMaNlfbssoMIXlXFLAOwY7S0JHfeXBLbJNGf8bB6AY,18060
+doc_code/errors.py,sha256=wx9jcsUQ9ValR4G1anQ1X6mwYoAn2VK2p9h_p30FqTE,603
+doc_code/git.py,sha256=1jvdI4alHj-Ntp5OziWWYsHhiw2HNSiqXWFh9Lex168,3077
+doc_code/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+doc_code/scope.py,sha256=JJb0j3SjDl5ryWi-xH-Z9HPxWJSvqZMGXBPzlG8LFEg,4072
+doc_code/symbols.py,sha256=B1hOgN8GqpGud0YZnYPR8Dtk_SIykq3YV6hd76UFWpc,24006
+doc_code-0.1.0.dist-info/licenses/LICENSE,sha256=vmqyc5Yy-tKx7me3iWqd6-xTGx8D69JcCd9WJcqrMu4,1084
+doc_code-0.1.0.dist-info/METADATA,sha256=Sqf1rqaklyPxfpx_mNa-ZRqmU4jrE6ghvL3pydcMXSs,9641
+doc_code-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+doc_code-0.1.0.dist-info/entry_points.txt,sha256=i7bxfl75gejcqGwialk_vT18XxcPb96N7FYT78Lbi70,47
+doc_code-0.1.0.dist-info/top_level.txt,sha256=zPxoC9HnlFTvtVW7TgflbND8JzCGPHYIF7tFaNbJYcA,9
+doc_code-0.1.0.dist-info/RECORD,,

doc_code-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

doc_code-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+doc-code = doc_code.cli:main

doc_code-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 André Argôlo (argolo.dev)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

doc_code-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+doc_code