No project description provided
Project description
DocLinter 📝: Python Docstring Complexity Analyzer
DocLinter is a command-line tool written in Python that helps you maintain consistent and readable documentation across your projects.
Features
- Lint the complexity of docstrings in Python files.
- Customize analysis by specifying a maximum complexity level.
- Easily integrate into your workflow with a simple command-line interface.
Installation
You can install DocLinter using pip:
pip install doclinter
Usage
To analyze the complexity of docstrings in Python files, use the following command:
doclinter <file_or_directory_glob>
Optional arguments:
--max-ari-level <int>
: Specify the maximum automated readability index to report as an error.-v, --verbose
: Display verbose output.
Example:
doclinter my_module.py --max-ari-level 10 -v
How It Works 🛠️
DocLinter utilizes the abstract syntax tree (AST) module in Python to parse Python files and extract docstrings. It rates the complexity of each docstring using the Automated Readability Index (ARI), a formula that takes into account factors such as word count, letter count, and sentence count. Docstrings with complexity levels above the specified threshold are reported as errors.
Why Use DocLinter? 🚀
- Enhance Documentation Quality: Ensure that your docstrings meet readability standards, making your codebase more accessible and maintainable.
- Catch Complex Docstrings: Identify and address overly complex docstrings that may hinder understanding and collaboration among team members.
- Improve Code Review Process: Streamline code reviews by flagging complex docstrings early in the development cycle, saving time and effort.
- Foster Best Practices: Encourage the adoption of clear and concise documentation practices across your projects, promoting consistency and professionalism.
Roadmap 🗺️
- Better reporting so you can find the function easily
- Arguments for ARI complexity thresholds
- Support linting multiple files at once
- Package on PyPI
- Make GitHub Actions task
- Improve documentation
- Support different measures of complexity (adverbs/passive voice...)
- Parse different kinds of Python docstrings to lint relevant parts
- Not just Python files, lint markdown too
- Support different formulas of complexity
- Support pyproject.toml configuration
Contributing
Contributions are welcome! If you encounter any issues or have suggestions for improvement, please submit an issue or create a pull request on GitHub.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgements
DocLinter is developed and maintained by Eugene Prout.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for doclinter-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7948a0aaf843d056b11a0c7ac9edf8f63e6302f7bf0859339154ccd83bf63cad |
|
MD5 | 0e1e7dabe8934a2340ab7363819244d3 |
|
BLAKE2b-256 | 5ac06285061bbcbee4138ed0f96191a6ade5b22924d7935b668df636acaf7f8a |