Store documents for sensor filters in separate files and sort entries #4735
Conversation
WalkthroughThe changes restructure the sensor filter documentation by extracting detailed descriptions, configuration variables, examples, and notes for each filter from the main Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant MainSensorDoc as Sensor Main Documentation
participant FilterDocs as Individual Filter Docs (.rst)
User->>MainSensorDoc: Access sensor filter documentation
MainSensorDoc-->>FilterDocs: Include filter documentation via .. include::
FilterDocs-->>User: Present detailed filter documentation
Suggested reviewers
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (26)
🚧 Files skipped from review as they are similar to previous changes (26)
✨ Finishing Touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
components/sensor/sensor-filter-quantile.rst (1)
1-36: Comprehensive and Well-Formatted Quantile Filter Documentation
The documentation for thequantilefilter is thorough with a clear description, a detailed YAML example, and an explanation of configuration variables including default values. Ensure that the default values mentioned are consistent with the actual implementation.components/sensor/sensor-filter-filter_out.rst (1)
1-28: Effective Documentation for the Filter_Out Feature
Thefilter_outdocumentation clearly explains the required parameter and provides multiple YAML examples (both single value and list-based filtering). Consider a slight rephrasing in the initial description for improved clarity—for instance, "Filter out specific values to be displayed, e.g., filtering out the value85.0."components/sensor/sensor-filter-calibrate_polynomial.rst (1)
1-27: Enhance Clarity with Minor Grammatical Adjustments
- Consider revising the sentence on line 6 from:
"Calibrate your sensor values by fitting them to a polynomial functions."
to:
"Calibrate your sensor values by fitting them to polynomial functions."- Optionally, review the length of the underline (line 4) relative to the heading text for consistent formatting.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (24)
components/sensor/index.rst(1 hunks)components/sensor/sensor-filter-calibrate_linear.rst(1 hunks)components/sensor/sensor-filter-calibrate_polynomial.rst(1 hunks)components/sensor/sensor-filter-clamp.rst(1 hunks)components/sensor/sensor-filter-debounce.rst(1 hunks)components/sensor/sensor-filter-delta.rst(1 hunks)components/sensor/sensor-filter-exponential_moving_average.rst(1 hunks)components/sensor/sensor-filter-filter_out.rst(1 hunks)components/sensor/sensor-filter-heartbeat.rst(1 hunks)components/sensor/sensor-filter-lambda.rst(1 hunks)components/sensor/sensor-filter-max.rst(1 hunks)components/sensor/sensor-filter-median.rst(1 hunks)components/sensor/sensor-filter-min.rst(1 hunks)components/sensor/sensor-filter-multiply.rst(1 hunks)components/sensor/sensor-filter-offset.rst(1 hunks)components/sensor/sensor-filter-or.rst(1 hunks)components/sensor/sensor-filter-quantile.rst(1 hunks)components/sensor/sensor-filter-round.rst(1 hunks)components/sensor/sensor-filter-round_to_multiple_of.rst(1 hunks)components/sensor/sensor-filter-skip_initial.rst(1 hunks)components/sensor/sensor-filter-sliding_window_moving_average.rst(1 hunks)components/sensor/sensor-filter-throttle.rst(1 hunks)components/sensor/sensor-filter-throttle_average.rst(1 hunks)components/sensor/sensor-filter-timeout.rst(1 hunks)
✅ Files skipped from review due to trivial changes (16)
- components/sensor/sensor-filter-round.rst
- components/sensor/sensor-filter-multiply.rst
- components/sensor/sensor-filter-heartbeat.rst
- components/sensor/sensor-filter-debounce.rst
- components/sensor/sensor-filter-median.rst
- components/sensor/sensor-filter-round_to_multiple_of.rst
- components/sensor/sensor-filter-timeout.rst
- components/sensor/sensor-filter-clamp.rst
- components/sensor/sensor-filter-or.rst
- components/sensor/sensor-filter-max.rst
- components/sensor/sensor-filter-lambda.rst
- components/sensor/sensor-filter-throttle_average.rst
- components/sensor/sensor-filter-delta.rst
- components/sensor/sensor-filter-exponential_moving_average.rst
- components/sensor/sensor-filter-throttle.rst
- components/sensor/index.rst
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
components/sensor/sensor-filter-offset.rstcomponents/sensor/sensor-filter-min.rstcomponents/sensor/sensor-filter-quantile.rstcomponents/sensor/sensor-filter-calibrate_polynomial.rstcomponents/sensor/sensor-filter-filter_out.rstcomponents/sensor/sensor-filter-skip_initial.rstcomponents/sensor/sensor-filter-sliding_window_moving_average.rstcomponents/sensor/sensor-filter-calibrate_linear.rst
🔇 Additional comments (18)
components/sensor/sensor-filter-skip_initial.rst (1)
1-16: Documentation Clarity and Organization
The introduction of theskip_initialfilter is clear and concise. The explanation and the YAML example are well-presented, making it easy for users to understand how the filter works.components/sensor/sensor-filter-offset.rst (1)
1-16: Clear Documentation for the Offset Filter
The description and examples for theoffsetfilter are clear and informative. The sample YAML configuration demonstrates both a static value and a lambda-based offset, which is helpful. Please double-check that the lambda syntax (!lambda return id(some_sensor).state;) conforms with the expected ESPHome conventions.components/sensor/sensor-filter-sliding_window_moving_average.rst (5)
1-3: Section Title and Heading:
The title is clearly marked with inline literals and the underline uses a consistent style typical for reStructuredText.
4-7: Descriptive Overview:
The introductory text succinctly explains the purpose of the sliding window moving average filter and provides a helpful link for further reading.
8-17: YAML Configuration Example:
The example configuration is well formatted and clearly demonstrates how to use the filter with its parameters. Users should find this example easy to follow.
18-28: Configuration Variables Section:
The configuration variable descriptions are clear and include type, optional status, and default values. Verify that the documented defaults align with the actual implementation.
29-31: Anchor Review:
The directive.. _sensor-filter-exponential_moving_average:appears at the end of the file. If this anchor is intended to link to external documentation for the exponential moving average filter, ensure it is referenced appropriately in the index or related documents. Otherwise, consider removing it to avoid confusion.components/sensor/sensor-filter-min.rst (4)
1-3: Section Title and Heading:
The heading is styled consistently with other documentation entries and clearly indicates that the file covers theminfilter.
4-6: Overview Description:
The brief explanation accurately describes the functionality and behavior of the moving minimum filter. The note on the impact of a larger window size is especially useful.
7-17: YAML Configuration Example:
The YAML code block effectively illustrates how to configure theminfilter with realistic parameter values. The indentation and format follow standard practices, making it easy for users to adopt.
18-30: Configuration Variables Documentation:
The documentation clearly outlines the purpose and default values ofwindow_size,send_every, andsend_first_at. It would be beneficial to verify that the stated defaults match those in the implementation.components/sensor/sensor-filter-calibrate_linear.rst (7)
1-2: Section Title and Heading:
The header uses inline literals forcalibrate_linearand is paired with an underline that conforms to reStructuredText conventions.
4-6: Introduction and Purpose:
The introductory text effectively explains the calibration purpose by highlighting how sensor values are adjusted using accurate reference measurements.
6-11: Configuration Variables Details:
The section outlining configuration variables likemethodanddatapointsis clear and precise. It specifies when each parameter is required and includes default values. Please verify that these defaults align with the actual code.
12-16: Calibration Guidance:
The additional guidance on collecting sensor values alongside true values is practical and useful for end users, particularly for calibrating different types of sensors.
17-31: YAML Configuration Example:
The YAML example provides a comprehensive configuration, including datapoint mapping that demonstrates the calibration process clearly. The formatting and indentation are consistent with reStructuredText standards.
32-36: Method Explanation and Limitations:
This section effectively explains the two calibration methods and warns users about the implications of supplying more than two datapoints with theleast_squaresmethod.
38-40: Figure Directive:
Including a figure enriches the documentation by providing a visual aid. Please ensure that the image located atimages/sensor_filter_calibrate_linear.pngexists and is correctly referenced.
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
rhabacker
force-pushed
the
sort-sensor-filter-docs
branch
from
dbcc06b to
8eb51c9
Compare
rhabacker
force-pushed
the
sort-sensor-filter-docs
branch
from
8eb51c9 to
7f17150
Compare
|
Ping ? |
rhabacker
force-pushed
the
sort-sensor-filter-docs
branch
from
e4cb84d to
c939734
Compare
rhabacker
force-pushed
the
sort-sensor-filter-docs
branch
from
c939734 to
ad92c95
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
changelog/v1.14.0.rst(1 hunks)components/sensor/sensor-filter-calibrate_polynomial.rst(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- components/sensor/sensor-filter-calibrate_polynomial.rst
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
changelog/v1.14.0.rst
🪛 GitHub Actions: Lint
changelog/v1.14.0.rst
[error] 310-310: Sphinx build error: undefined label 'sensor-filter-calibrate_polynomial' treated as error.
rhabacker
force-pushed
the
sort-sensor-filter-docs
branch
from
ad92c95 to
e064bcc
Compare
Entering the new files in the “exclude_pattern” configuration setting ensures that the new files are not also included in the table of contents.
rhabacker
force-pushed
the
sort-sensor-filter-docs
branch
from
e064bcc to
171a718
Compare
|
@clydebarrow: Can you refer me to someone who can check and merge this pull request ? |
Description:
When working on #4485, it turned out that the documentation for sensor filters is not really easy to customize, as they are all contained in an unsorted order in a single file. With this pull request, they are stored in individual files and sorted in the index file, which will make maintenance and reading easier in the future.
Related issue (if applicable): fixes
Pull request in esphome with YAML changes (if applicable):
Checklist:
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/components/index.rstwhen creating new documents for new components or cookbook.