📋 Overview
Significantly expand the project documentation with comprehensive usage guides and detailed CLI walkthroughs. This release also introduces performance optimisations for file discovery on Linux systems, refines the integration instructions for pre-commit, and standardises the grammatical tone across the entire codebase.
✨ New Features
📘 Introduce comprehensive usage documentation
Create three new major documentation sections to assist developers at all experience levels.
- Provide a clear installation path and a guided first check in the getting_started.md guide.
- Detail every global and section-specific configuration option with practical examples and troubleshooting tips in the configuration.md page.
- Deliver an extensive walkthrough of command-line interactions, including sample terminal outputs and format comparisons, in the command_line_interface.md guide.
🚀 Optimise file discovery performance
Refactor the get_all_files() function in scripts.py to utilise the Linux find command for significantly faster file retrieval in large repositories. Maintain a robust fallback to the Path.glob() method to ensure cross-platform compatibility.
⚙️ Technical Improvements
🛡️ Refine file exclusion logic for documentation
Enhance the check_blacken_docs() and run_blacken_docs() functions to exclude documentation markdown files from the blacken-docs process. This ensures that intentional "bad" code examples used for demonstration purposes remain unfixed by the formatter, preserving their educational value.
🔗 Improve pre-commit and installation guides
Update the README.md with modern installation instructions for every major package manager, referencing the latest 1.* version. Introduce a dedicated section for pre-commit integration with an example configuration for .pre-commit-config.yaml to help users automate their docstring validation.
🛠️ Clean up internal callbacks and metadata
Remove redundant parameter descriptions for ctx, param, and value within the _show_usage_examples_callback() and _show_config_example_callback() functions in cli.py. Update the GlobalConfig() and SectionConfig() dataclasses in config.py with descriptive field() metadata to improve IDE tooltip clarity.
✍️ Documentation and Styling
🎨 Enhance visual documentation styling
Introduce custom CSS styling in code_chunks.css to display the TOML logo icon next to configuration code blocks. Update the mkdocs.yaml configuration to enable the content.code.select and content.code.copy features, and standardise the code font to improve readability.
📋 Standardise internal grammatical tone
Perform a comprehensive linguistic sweep to ensure that all internal docstrings and comments follow a consistent grammatical structure. Standardise descriptions of dfc behaviour to use the third-person singular (e.g., "reports", "fails", "checks") to provide a professional and unified tone throughout the project.
💪 Pull Requests
- Enhance documentation, introduce comprehensive usage guides, and improve file discovery performance by @chrimaho in #39
Full Changelog: v1.11.3...v1.11.4
