Refactor: PEP 257 docstrings, 80 char line limit, and comprehensive documentation#24
Merged
Refactor: PEP 257 docstrings, 80 char line limit, and comprehensive documentation#24
Conversation
…ocumentation Major Changes: - Applied PEP 257 docstring conventions across all Python modules - Migrated from 100 to 80 character line limit per PEP 8 - Comprehensive documentation refactor with improved organization Code Changes: - Updated all docstrings to follow PEP 257 format (one-line summaries, proper spacing) - Reformatted code to adhere to 80 character line limit - Enhanced inline documentation throughout the codebase - Improved type hints and function signatures Documentation Changes: - Reorganized Sphinx documentation for better discoverability - Created structured sections: Installation, Quickstart, Python API, Protocol, Guides, Development - Added comprehensive API client, MQTT client, and Auth client documentation - Created user guides for Time of Use, Reservations, Energy Monitoring, and Events - Added protocol documentation for REST API and MQTT messages - Included complete module-level API reference with autodoc - Added OpenEI integration example for TOU schedules - Removed redundant/outdated documentation files New Documentation Files: - docs/installation.rst - Installation instructions - docs/quickstart.rst - Quick start guide - docs/configuration.rst - Configuration reference - docs/python_api/*.rst - Python API documentation (auth, api_client, mqtt_client, models, etc.) - docs/protocol/*.rst - REST API and MQTT protocol documentation - docs/guides/*.rst - User guides (TOU, reservations, energy monitoring, events) - docs/development/*.rst - Development and contribution guides Removed Files: - Consolidated and removed obsolete RST files (API_CLIENT.rst, MQTT_CLIENT.rst, etc.) - Removed temporary scripts and status files All changes maintain backward compatibility and pass CI checks (linting, type checking, tests).
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
…sensitive information Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
…sensitive information Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR implements a comprehensive refactor to improve code quality and documentation structure by migrating to an 80-character line limit, applying PEP 257 docstring conventions, and reorganizing Sphinx documentation into a logical hierarchy. The changes improve readability, maintainability, and provide comprehensive API and protocol documentation while maintaining full backward compatibility.
Key Changes:
- Applied PEP 257 docstring conventions across all Python modules with one-line summaries and proper spacing
- Migrated from 100 to 80 character line limit as specified in pyproject.toml
- Reorganized documentation into Installation, Quickstart, Python API, Protocol, User Guides, and Development sections
Reviewed Changes
Copilot reviewed 63 out of 65 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| pyproject.toml | Updated line-length configuration from 100 to 80 characters |
| tests/*.py | Reformatted to 80-char line limit with proper line breaks for function calls |
| src/nwp500/*.py | Applied PEP 257 docstrings and 80-char line limit throughout core modules |
| src/nwp500/cli/*.py | Reformatted CLI modules with improved docstrings and line breaks |
| docs/*.rst | Created comprehensive documentation structure with API reference, guides, and protocol details |
| examples/*.py | Added OpenEI integration example and updated README with detailed usage instructions |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
- Remove redundant int() cast (casting int to int is no-op) - Clarify comments to indicate float vs int handling - Fix unrelated line length issues in mqtt_utils.py
…ted method - Simplify price encoding logic in build_tou_period() by checking if NOT int first (avoids redundant int-to-int casting and mypy unreachable code warnings) - Remove deprecated _start_reconnect_task() method from NavienMqttClient (reconnection is now fully handled by MqttReconnectionHandler)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR implements a comprehensive refactor of the codebase to adhere to Python coding standards and improves the documentation structure significantly.
Code Changes
PEP 257 Compliance
PEP 8 Line Length
Code Quality
Documentation Changes
New Structure
Reorganized Sphinx documentation into logical sections:
New Documentation Files
docs/installation.rst- Installation instructionsdocs/quickstart.rst- Quick start guidedocs/configuration.rst- Configuration referencedocs/python_api/- Comprehensive API docs (auth_client, api_client, mqtt_client, models, events, constants, CLI, exceptions)docs/protocol/- REST API and MQTT protocol documentationdocs/guides/- User guides for TOU, Reservations, Energy Monitoring, Events, Auto Recovery, Command Queuedocs/development/- Contributing guide and project historyAPI Documentation
User Guides
Protocol Documentation
Examples
examples/tou_openei_example.py- Demonstrates OpenEI API integration for TOU schedulesCleanup
Testing
✅ All linting checks pass (
make ci-lint)✅ Type checking passes (
python3 -m mypy src/nwp500)✅ Documentation builds without warnings (
tox -e docs)✅ All tests pass (
pytest)Breaking Changes
None - all changes are backward compatible
Files Changed