{"id":31396255,"url":"https://github.com/jmorgadov/dolce","last_synced_at":"2025-09-29T11:17:25.745Z","repository":{"id":314916722,"uuid":"1057228209","full_name":"jmorgadov/dolce","owner":"jmorgadov","description":"Advanced Python documentation management tool. Performs static and LLM-powered docstrings validations, generates missing docstrings, detects semantic inconsistencies, and much more.","archived":false,"fork":false,"pushed_at":"2025-09-22T17:26:28.000Z","size":472,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-22T19:28:36.248Z","etag":null,"topics":["ai","docstrings","documentation","llm","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jmorgadov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-15T12:53:05.000Z","updated_at":"2025-09-22T17:26:33.000Z","dependencies_parsed_at":"2025-09-15T17:20:51.570Z","dependency_job_id":"fdbf0e7d-2f6a-4fbf-9a1f-a40a9633fd17","html_url":"https://github.com/jmorgadov/dolce","commit_stats":null,"previous_names":["jmorgadov/dolce"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jmorgadov/dolce","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmorgadov%2Fdolce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmorgadov%2Fdolce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmorgadov%2Fdolce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmorgadov%2Fdolce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jmorgadov","download_url":"https://codeload.github.com/jmorgadov/dolce/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmorgadov%2Fdolce/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277503620,"owners_count":25829236,"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-09-29T02:00:09.175Z","response_time":84,"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":["ai","docstrings","documentation","llm","python"],"created_at":"2025-09-29T11:17:24.649Z","updated_at":"2025-09-29T11:17:25.729Z","avatar_url":"https://github.com/jmorgadov.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dolce\n\n***Because broken docs leave a bitter taste.***\n\n\u003ca ref=\"https://pypi.org/project/pydolce/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/pydolce?color=blue\u0026label=PyPI\u0026logo=python\u0026style=flat-square\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n\n**Dolce** is a tool designed to help you maintain high-quality docstrings/documentation in your Python code. In addition, it leverages Large Language Models (LLMs) to ensure that your docstrings are semantically consistent with your code.\n\n\u003e [!NOTE]\n\u003e **Dolce** is still in early development. While it is functional, some features are yet to be implemented and improvements are ongoing. Your feedback and contributions are highly appreciated!\n\n## 🚀 Quick showcase\n\nCheck docstrings issues with static and LLM-powered rules:\n\u003cimg src=\"docs/src/statics/check.svg\"/\u003e\n\nSuggest missing docstrings by leveraging LLMs:\n\n\u003cimg src=\"docs/src/statics/sugg.svg\"/\u003e\n\nRestyle your entire codebase docstrings to a consistent format:\n\n\u003cimg src=\"docs/src/statics/restyle.svg\"/\u003e\n\n## ✨ Features\n\n- **Comprensive Rule Set**: Comes with a variety of built-in rules to check for common docstring issues, including:\n  Static rules:\n  - Missing docstrings\n  - Incomplete parameter documentation\n  - Signature mismatches\n  .. etc\n\n  and LLM-powered rules:\n  - Consistency between code and docstring\n  - Detection of undocumented critical behaviors\n  ... etc\n- **Generation docstrings**: Generate missing docstrings across your codebase (with the help of LLMs) by running a single command.\n- **Restyling**: Automatically restyle your existing docstrings to a consistent format (Google, NumPy, ReST, Epy, etc.).\n- **Cache system**: Avoid re-checking unchanged code.\n- **Customizable**: Easily configure which rules to apply, LLMs config (model, provider, url, etc.), and other settings via a `pyproject.toml` file.\n\n... more features coming soon!\n\n## 📦 Installation\n\nYou can install **dolce** globally via pip:\n\n```bash\npip install pydolce\n```\n\nHowever, the recommended use is to install it as a dev dependency in your project environment. If you are using [uv](https://docs.astral.sh/uv/) for managing your Python projects, you can add it to your `pyproject.toml` like this:\n\n```bash\nuv add pydolce --group dev\n```\n\n\u003e Don't forget to sync: `uv sync --all-groups`\n\nThen you can use it by running:\n\n```bash\nuv run dolce [COMMAND]\n```\n\n## 💻 Usage\n\n### Check docstrings\n\n```bash\ndolce check [PATH] # If no PATH is provided it will check the current directory\n```\n\n### Generate missing docstrings\n\n```bash\ndolce suggest [PATH] # If no PATH is provided it will run in the current directory\n```\n\n### Quick reference of available rules\n\n```bash\ndolce rules\n```\n\n## ⚙️ Configure\n\n**Dolce** can be configured via `pyproject.toml` file. You can specify which rules to check and which to ignore. By default it will check all rules.\n\n```toml\n[tool.dolce]\ntarget = [\n  # Set of rules to check\n  \"DCE101\",\n]\ndisable = [\n  # Set of rules to ignore\n  \"DCE102\",\n]\n```\n\n### Use of LLM\n\nBy default **dolce** does not make use of LLM features (like smart check rules or doccstring suggestions). To enable them you need to configure the LLM options in the `pyproject.toml` file like this:\n\n```toml\n[tool.dolce]\nurl = \"http://localhost:11434\"\nmodel = \"qwen3:8b\"\nprovider = \"ollama\"\napi_key = \"YOUR_API_KEY_ENVIROMENT_VAR\" # Optional, needed for non local providers\n```\n\n\u003e [!TIP]\n\u003e `qwen3:8b` has relatively good performance while fitting in an RTX 4060 GPU (8GB VRAM)\n\nYou can visit the [Ollama](https://ollama.com/) to check how to install and run models locally.\n\n## To be implemented\n\n- Add cache system to avoid re-checking unchanged code\n- Support for ignoring specific code segments, files, directories, etc\n- Support parallel requests\n... much more!\n\n---\n\n## 👩‍💻 For Developers\n\nMake sure you have the following tools installed before working with the project:\n\n- [**uv**](https://docs.astral.sh/uv/) → Python project and environment management\n- [**make**](https://www.gnu.org/software/make/) → run common project tasks via the `Makefile`\n\n### Getting Started\n\nInstall dependencies into a local virtual environment:\n\n```bash\nuv sync --all-groups\n```\n\nThis will create a `.venv` folder and install everything declared in `pyproject.toml`.\n\nThen, you can activate the environment manually depending on your shell/OS:\n\n- **Linux / macOS (bash/zsh):**\n\n  ```bash\n  source .venv/bin/activate\n  ```\n\n- **Windows (PowerShell):**\n\n  ```powershell\n  .venv\\Scripts\\Activate.ps1\n  ```\n\n- **Windows (cmd.exe):**\n\n  ```cmd\n  .venv\\Scripts\\activate.bat\n  ```\n\n### Running\n\n```bash\nuv run dolce check path/to/your/code\n```\n\n### Linting, Formatting, and Type Checking\n\n```bash\nmake qa\n```\n\nRuns **Ruff** for linting and formatting, and **Mypy** for type checking.\n\n### Running Unit Tests\n\nBefore running tests, override any required environment variables in the `.env.test` file.\n\n```bash\nmake test\n```\n\nExecutes the test suite using **Pytest**.\n\n### Building the Project\n\n```bash\nmake build\n```\n\nGenerates a distribution package inside the `dist/` directory.\n\n### Cleaning Up\n\n```bash\nmake clean\n```\n\nRemoves build artifacts, caches, and temporary files to keep your project directory clean.\n\n### Building docs\n\n```bash\nmake docs\n```\n\nGenerates the project documentation inside the `dist/docs` folder.\n\nWhen building the project (`make build`) the docs will also be generated automatically and\nincluded in the distribution package.\n\n## 🤝 Contributing\n\nContributions are welcome!\nPlease ensure all QA checks and tests pass before opening a pull request.\n\n---\n\n\u003csub\u003e🚀 Project starter provided by [Cookie Pyrate](https://github.com/gvieralopez/cookie-pyrate)\u003c/sub\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmorgadov%2Fdolce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmorgadov%2Fdolce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmorgadov%2Fdolce/lists"}