DocLinter is a command-line tool written in Python that helps you maintain consistent and readable documentation across your projects.
- 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.
You can install DocLinter using pip:
pip install doclinter
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
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.
- 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.
- 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
Contributions are welcome! If you encounter any issues or have suggestions for improvement, please submit an issue or create a pull request on GitHub.
This project is licensed under the MIT License - see the LICENSE file for details.
DocLinter is developed and maintained by Eugene Prout.