Skip to content

Store documents for sensor filters in separate files and sort entries #4735

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 6, 2025

Conversation

rhabacker
Copy link
Contributor

@rhabacker rhabacker commented Mar 6, 2025

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.

grafik

Related issue (if applicable): fixes

Pull request in esphome with YAML changes (if applicable):

  • esphome/esphome#

Checklist:

  • I am merging into next because this is new documentation that has a matching pull-request in esphome as linked above.
    or

  • I am merging into current because 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.rst when creating new documents for new components or cookbook.

Copy link
Contributor

coderabbitai bot commented Mar 6, 2025

Walkthrough

The changes restructure the sensor filter documentation by extracting detailed descriptions, configuration variables, examples, and notes for each filter from the main components/sensor/index.rst file into separate, dedicated .rst files. The main documentation now references these files using .. include:: directives, centralizing filter documentation and improving modularity. New .rst files have been created for each sensor filter, providing focused documentation for filters such as offset, multiply, calibrate_linear, clamp, debounce, delta, and others. Additionally, the Sphinx configuration (conf.py) was updated to exclude these new filter documentation files from certain build processes. The changelog was also updated to correct a documentation link for the calibrate_polynomial filter.

Changes

File(s) Change Summary
components/sensor/index.rst Refactored to remove inline filter documentation; now uses .. include:: directives to reference new filter .rst files.
components/sensor/sensor-filter-*.rst (all new files for each filter) Added dedicated documentation files for each sensor filter, each detailing configuration, usage, and YAML examples.
conf.py Updated exclude_patterns to include components/sensor/sensor-filter-*.rst, affecting Sphinx documentation builds.
changelog/v1.14.0.rst Corrected reference link for calibrate_polynomial sensor filter in changelog entry.

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
Loading

Suggested reviewers

  • jesserockz

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e064bcc and 171a718.

📒 Files selected for processing (26)
  • changelog/v1.14.0.rst (1 hunks)
  • 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)
  • conf.py (1 hunks)
🚧 Files skipped from review as they are similar to previous changes (26)
  • components/sensor/sensor-filter-heartbeat.rst
  • components/sensor/sensor-filter-multiply.rst
  • components/sensor/sensor-filter-round_to_multiple_of.rst
  • components/sensor/sensor-filter-throttle.rst
  • changelog/v1.14.0.rst
  • components/sensor/sensor-filter-round.rst
  • components/sensor/sensor-filter-max.rst
  • components/sensor/sensor-filter-clamp.rst
  • components/sensor/sensor-filter-or.rst
  • components/sensor/sensor-filter-timeout.rst
  • conf.py
  • components/sensor/sensor-filter-min.rst
  • components/sensor/sensor-filter-calibrate_polynomial.rst
  • components/sensor/sensor-filter-lambda.rst
  • components/sensor/sensor-filter-delta.rst
  • components/sensor/sensor-filter-exponential_moving_average.rst
  • components/sensor/index.rst
  • components/sensor/sensor-filter-skip_initial.rst
  • components/sensor/sensor-filter-sliding_window_moving_average.rst
  • components/sensor/sensor-filter-debounce.rst
  • components/sensor/sensor-filter-filter_out.rst
  • components/sensor/sensor-filter-quantile.rst
  • components/sensor/sensor-filter-offset.rst
  • components/sensor/sensor-filter-median.rst
  • components/sensor/sensor-filter-throttle_average.rst
  • components/sensor/sensor-filter-calibrate_linear.rst
✨ Finishing Touches
  • 📝 Generate Docstrings

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.

❤️ Share
🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Generate unit testing code for this file.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai generate unit testing code for this file.
    • @coderabbitai modularize this function.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and generate unit testing code.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
    • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need 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)

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai generate docstrings to generate docstrings for this PR.
  • @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

  • You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
  • Please see the configuration documentation for more information.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 the quantile filter 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
The filter_out documentation 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 value 85.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

📥 Commits

Reviewing files that changed from the base of the PR and between da90429 and 505e3ed.

📒 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.rst
  • components/sensor/sensor-filter-min.rst
  • components/sensor/sensor-filter-quantile.rst
  • components/sensor/sensor-filter-calibrate_polynomial.rst
  • components/sensor/sensor-filter-filter_out.rst
  • components/sensor/sensor-filter-skip_initial.rst
  • components/sensor/sensor-filter-sliding_window_moving_average.rst
  • components/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 the skip_initial filter 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 the offset filter 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 the min filter.


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 the min filter 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 of window_size, send_every, and send_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 for calibrate_linear and 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 like method and datapoints is 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 the least_squares method.


38-40: Figure Directive:
Including a figure enriches the documentation by providing a visual aid. Please ensure that the image located at images/sensor_filter_calibrate_linear.png exists and is correctly referenced.

Copy link

netlify bot commented Mar 6, 2025

Deploy Preview for esphome ready!

Name Link
🔨 Latest commit 171a718
🔍 Latest deploy log https://app.netlify.com/sites/esphome/deploys/681a6ed56361fe0008724c3b
😎 Deploy Preview https://deploy-preview-4735--esphome.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@rhabacker rhabacker force-pushed the sort-sensor-filter-docs branch from dbcc06b to 8eb51c9 Compare March 7, 2025 15:42
@rhabacker rhabacker force-pushed the sort-sensor-filter-docs branch from 8eb51c9 to 7f17150 Compare April 14, 2025 22:55
@rhabacker
Copy link
Contributor Author

Ping ?

rhabacker added a commit to rhabacker/esphome-docs that referenced this pull request Apr 15, 2025
rhabacker added a commit to rhabacker/esphome-docs that referenced this pull request Apr 15, 2025
@rhabacker rhabacker force-pushed the sort-sensor-filter-docs branch from e4cb84d to c939734 Compare April 15, 2025 20:22
rhabacker added a commit to rhabacker/esphome-docs that referenced this pull request Apr 15, 2025
@rhabacker rhabacker force-pushed the sort-sensor-filter-docs branch from c939734 to ad92c95 Compare April 15, 2025 20:32
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c939734 and ad92c95.

📒 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 added a commit to rhabacker/esphome-docs that referenced this pull request Apr 15, 2025
@rhabacker rhabacker force-pushed the sort-sensor-filter-docs branch from ad92c95 to e064bcc Compare April 15, 2025 20:46
rhabacker added 3 commits May 6, 2025 22:19
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 rhabacker force-pushed the sort-sensor-filter-docs branch from e064bcc to 171a718 Compare May 6, 2025 20:19
@rhabacker
Copy link
Contributor Author

@clydebarrow: Can you refer me to someone who can check and merge this pull request ?

@clydebarrow clydebarrow merged commit a049eb3 into esphome:current May 6, 2025
3 checks passed
@github-actions github-actions bot locked and limited conversation to collaborators May 8, 2025
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants