Move docs off of main page #4706
Conversation
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
kbx81
force-pushed
the
20250224-move-docs
branch
from
adb45fd to
a73651b
Compare
WalkthroughThis pull request updates several reStructuredText documentation files. In one file, the Changes
Possibly related PRs
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
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 (1)
docs.rst (1)
9-10: Image Directive Path ConsistencyThe image directive on line 9 uses an absolute path (
/images/logo-docs.svg). Verify that this is intentional and consistent with other documentation files where relative paths (e.g.,images/logo-text.svg) are used. If relative paths are preferred for portability, update this accordingly.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs.rst(1 hunks)guides/contributing.rst(0 hunks)index.rst(3 hunks)
💤 Files with no reviewable changes (1)
- guides/contributing.rst
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
docs.rstindex.rst
🔇 Additional comments (8)
docs.rst (3)
1-8: Metadata and SEO Block Look SolidThe title, meta, and SEO directives are clear and well-formed. This section provides a strong introductory identity for the documentation file.
11-30: Introduction and Overview SectionThe introductory text and the initial description (e.g., “This page is an index of all of the hardware components…”) are well written. The content clearly outlines the structure and intent of the file. The use of directive blocks (like
.. imgtable::) for presenting supported microcontrollers appears well organized.
31-1087: Comprehensive Content OrganizationThis new documentation file covers a vast array of ESPHome components and peripherals. The segmented sections—with headers and imgtable directives—improve readability and provide detailed visual guidance. Overall, the organization is comprehensive and should serve as a robust reference for users. Please perform a final check on all image paths and references to ensure they resolve correctly in the final build.
index.rst (5)
12-13: Updated Logo Image PathThe image directive on line 12 now uses the relative path
images/logo-text.svginstead of an absolute one. This update increases consistency within the repository and aids portability. Ensure that the referenced file exists in the specified location.
15-16: Refined Introductory MessageThe revised description — “ESPHome is a system which allows you to turn common microcontrollers into smart home devices.” — is both concise and clear. This improved wording aligns well with the documentation’s purpose.
17-18: Hero Image Path UpdateThe new hero image is now referenced with a relative path (
images/hero.png), which maintains consistency with the logo image update. Confirm that the hero image file is correctly placed relative to the document root.
141-147: New Documentation Section with Reference LabelThe addition of the Documentation section (with the new reference label
.. _documentation:on line 141) is a great improvement. The link text “You will find all :doc:ESPHome documentation here<docs>.” clearly guides users to the comprehensivedocs.rstfile. This change effectively moves documentation content off the main page as intended.
159-163: Updated Toctree with Documentation EntryThe modifications to the toctree (including the
docsentry on line 159) ensure that the new documentation file is part of the navigational hierarchy. This improves discoverability and integration with the rest of the documentation.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (8)
docs.rst (8)
1-8: Metadata and SEO Block – Looks Good and Informative
The title, SEO metadata, and image references provide a solid introduction. Verify that the logo used in the SEO block (i.e.logo.svg) is consistent with the one displayed later (i.e./images/logo-docs.svg) to ensure branding consistency.
19-26: Microcontroller Image Table Details
This image table lists several microcontrollers along with their associated image files. The addition of thedark-invertattribute for some entries (e.g. “Host”) is consistent, yet it would be good to confirm that the styling is intentional across the board.
27-36: Microcontroller Peripherals Section
The “Microcontroller Peripherals” section includes a brief description and an image table. The content is clear and sets the context well. A small nitpick: ensure consistent spacing and styling in the header formatting to match other sections.
37-43: ESPHome Automations Introduction
The introductory text for ESPHome Automations is engaging. The stylized quotation "When this happens, I want it to do that..." draws attention; however, consider standardizing the quotation style (e.g. using smart quotes or a consistent emphasis method) for uniformity.
161-180: I/O Expanders/Multiplexers Section
This comprehensive listing is clear and thorough. Revisit the captions to ensure clarity and consistency (for example, check that naming conventions like “BK72xx” vs. “RTL87xx” are standardized across similar components).
190-242: Sensor Components – Core and Air Quality Subsections
This expansive section successfully covers a wide array of sensors with detailed imgtable directives. Given its length, consider:
- Adding sub-headers or a table of contents within the document for easier navigation.
- Verifying that every image reference (e.g.
ads1115.jpg,scd30.jpg) is correct and available.
Overall, the comprehensive nature enhances the document’s value.
242-1026: Remaining Component Sections (Analogue, Digital, Environmental, Health/Safety, etc.)
The subsequent sections continue with a consistent pattern: each category has a well-structured header and an accompanying image table. Key points include:
- Ensuring that every file path (e.g. those under
components/sensor/,components/display/, etc.) accurately matches the repository’s file structure.- Maintaining visual consistency in the use of icons and attributes (like
dark-invert) across similar types of components.- For very extensive sections, consider introducing additional navigation aids (such as an internal TOC) to help users quickly find the section of interest.
Overall, the detailed categorization greatly supports user exploration of ESPHome’s capabilities.
1082-1087: Contributing Section
The Contributing section is brief and to the point, directing users to the relevant contributing guidelines. It might be beneficial to include a direct hyperlink or reference to a more detailed contributor guide if one exists elsewhere in the repository.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs.rst(1 hunks)index.rst(2 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- 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
docs.rst
🔇 Additional comments (13)
docs.rst (13)
9-12: Logo Image and Introductory Text
The use of the image directive with/images/logo-docs.svgand the clear introductory text immediately orient the reader. The concise description that follows sets the stage for the document.
13-18: Supported Microcontrollers Header
The section header “Supported Microcontrollers” is clear, and the inclusion of theimgtable::directive suggests a well-formatted presentation. Please double-check that all referenced image paths (e.g.esp32.svg,esp8266.svg, etc.) exist in the designated directories.
44-49: Automations Image Table Section
The automations section is clear and uses an image table to illustrate key topics (Overview, Actions, Conditions, Templates). Make sure that paths likeautomations/indexresolve correctly in the documentation build.
50-60: ESPHome Components Section
This section effectively categorizes ESPHome-specific components with a clear heading and a well-structured imgtable. The consistent use of image paths and optional attributes likedark-invertimproves readability.
70-79: ESPHome Configuration Section
The “ESPHome Configuration” section is succinct and clear. The image table entries (for External Components, Packages, Substitutions) appear accurate. It’s recommended to verify that the file paths (e.g.components/packages) match the repository structure.
80-88: Network Hardware Section
The network hardware segment is concise and properly formatted. Ensure that all referenced icons (likenetwork-wifi.svgandethernet.svg) are present and conform to the site’s visual standards.
89-102: Network Protocols Section
This section is detailed and provides a comprehensive list of network-related components via an image table. Confirm that icons such asserver-network.svg,mqtt.png, and others are uniform in style, which aids in a cohesive user experience.
103-112: Bluetooth/BLE Section
The presentation of Bluetooth/BLE components using an image table is well executed. The consistent use of attributes likedark-invertfor certain images underlines an intentional design choice.
114-125: Management and Monitoring Section
This part of the document cleanly lists components for debugging and monitoring using a well-formed imgtable. It effectively communicates available tools (e.g. Logger, Prometheus). No issues noted.
127-137: Update Installation Section
A brief but clear section. The simple presentation via an image table makes it easy for users to grasp the update installation options. Verify that the update images and references are current.
138-147: Update Management Section
This segment follows the style of the previous sections. The image table listing update management components is well designed.
148-160: Hardware Peripheral Interfaces/Busses
The section categorizes bus interfaces clearly. The consistent formatting and image table use across entries help in quick reference.
181-189: CAN Bus Section
A concise and clear section prepared with an image table. No further issues identified in this segment.
kbx81
force-pushed
the
20250224-move-docs
branch
from
4f36c75 to
f062ffa
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
components/index.rst (6)
1-6: Title & SEO Metadata Consistency
The title has been updated to "ESPHome Docs" and the SEO block now includes a description and image reference. Please double‑check that the generic description ("ESPHome main documentation") and the image filename ("logo-docs.svg") accurately represent the current content and branding.
13-23: Supported Microcontrollers Section Formatting
The "Supported Microcontrollers" section introduces an imgtable listing several devices. Notice that only the "Host" entry includes thedark-invertoption. Please review if this styling should be applied uniformly across all entries or deliberately only for selected components.
35-41: ESPHome Automations Section Enhancement
The automations section features a quoted example and a short explanation. Consider whether additional context or cross‑references might further assist users in understanding customizable automations.
188-240: Sensor Components Core Section
The "Sensor Components" area provides a detailed imgtable with many sensor entries. Since this is a very comprehensive list, it’s important to validate that each description and image file is correct. Consider whether automated checks for image link validity might be beneficial for long lists like this.
341-398: Environmental & Related Sensors Grouping
This large block—including sensors for temperature, pressure, CO₂, etc.—is very detailed. Given the volume, consider whether additional internal categorization might improve maintainability. Ensure that image assets are current and that descriptions are precise.
1086-1123: Table of Contents (toctree) Validation
The toctree directive now lists a wide range of component subsections. Please verify that the globbing and the:hidden:option produce the expected sidebar navigation and that all referenced paths (e.g.,binary_sensor/index,display/index) exist in their new locations.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
images/xiaomi_lywsd03mmc.jpgis excluded by!**/*.jpg
📒 Files selected for processing (3)
components/index.rst(1 hunks)guides/contributing.rst(0 hunks)index.rst(5 hunks)
💤 Files with no reviewable changes (1)
- guides/contributing.rst
🚧 Files skipped from review as they are similar to previous changes (1)
- 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/index.rst
🔇 Additional comments (68)
components/index.rst (68)
7-10: Image Directive Path Check
Line 7 uses an absolute path (/images/logo-docs.svg) while the SEO block uses a relative filename. Verify whether the image directive should use a relative path for consistency with the new documentation structure.
11-12: Reference Label Usage
The reference label (.. _devices:) is correctly added to improve navigation.
25-33: Microcontroller Peripherals Clarity
The brief description on line 28 and the subsequent imgtable are clear and well‑structured. Ensure that the paths (e.g.,components/psram) resolve correctly after reorganizing the docs.
42-47: Automation Imgtable Consistency
The imgtable for automations shows consistent formatting; verify that assets such asdescription.svgare up‑to‑date with the new structure.
48-67: ESPHome Components Detail
This section offers a comprehensive list of ESPHome‑specific components. Please confirm that each imgtable entry’s image files exist in their new locations and that any use of styling options (e.g.,dark-invert) is consistent with the updated design guidelines.
68-78: ESPHome Configuration Section Check
The "ESPHome Configuration" section is clearly introduced and paired with an imgtable. Verify that the listed paths (for External Components, Packages, and Substitutions) accurately reflect the reorganized documentation structure.
79-100: Network Hardware & Protocols Consistency
Both the Network Hardware and Network Protocols sections employ imgtables with image references (e.g.,network-wifi.svg,server-network.svg). Please check that the file paths are correct—especially if relative paths are now preferred—and that visual styling is consistent across these sections.
101-111: Bluetooth/BLE Section Review
The Bluetooth/BLE section is structured with an imgtable listing devices like "ESP32 BLE Beacon" and "ESP32 BLE Client." Confirm that the use ofdark-invert(if needed) is applied consistently and that the image assets are properly linked.
112-124: Management & Monitoring Section Inspection
This section, which includes components such as Debug, Logger, and Prometheus, is well‑formatted. As a reminder, check that any mixing of thedark-invertoption with non‑styled entries is intentional and aligns with the overall style guide.
125-136: OTA Update Installation Clarity
The Update Installation section (lines 125–136) explains OTA updates and pairs it with an imgtable. Ensure that the referenced images (likesystem-update.svg) are correctly updated and that the presentation is consistent with the rest of the documentation.
137-145: Update Management Details
The Update Management section is concise and clear. Double‑check that the imgtable entries accurately reflect any new updates or reorganized components in the docs.
146-178: Hardware Peripheral Interfaces & I/O Expanders
This section covers bus interfaces and I/O components. Given the variety of image file formats (e.g.,.svgversus.jpg), confirm that each asset is available and that the overall formatting supports easy maintenance post‑migration.
179-187: CAN Bus Section Precision
The CAN Bus section is brief and to‑the‑point. Verify that the image paths and component names are up‑to‑date with the new documentation tree.
241-254: Analogue Sensor Components Consistency
The analogue sensor section is clearly delineated. All entries appear to follow the same formatting rules; please review that commas, spacing, and image references (e.g.,adc128s102.png) are consistent.
255-270: Bluetooth Low Energy (BLE) Sensors
The BLE sensor entries are well‑formatted and clearly listed. Verify that the image filenames and any accompanying modifiers (e.g.,dark-invert) are consistent with overall style expectations.
271-280: Digital Signals Section
The digital signals section uses clear descriptors along with icon references likepercent.svgandpulse.svg. This formatting meets expectations.
281-294: Distance Sensor Components Review
The distance sensor entries are grouped effectively. Please ensure that file names (e.g.,jsn-sr04t-v3.jpg) are correct and that the descriptions match the intended functionality for clarity.
295-333: Electricity Sensor Components Detailing
This extensive list covers many electricity-related sensors. It may be worthwhile to confirm that naming conventions (e.g., ADE7880, ATM90E26, etc.) are uniform and that each imgtable entry has correctly referenced images.
334-340: Environmental Sensor Components
The environmental sensors begin with a clear imgtable and use assets likewater-drop.svg. Confirm that these entries are consistent with both formatting and visual expectations.
399-400: Final Sensor Entries Check
Ensure that the final sensor entries (such as the XGZP68xx Series) are clearly defined and that no entries are unintentionally omitted.
401-408: Health/Safety Sensor Components
The Health/Safety section includes mmWave sensor components and related devices. Verify that image references likeseeed_mr60bha2.jpgremain correct after the docs reorganization.
409-436: Light Sensor Components Evaluation
The light sensor section is thorough. Confirm that assets (e.g.,bh1750.jpg,ltr501.jpg) are updated and that descriptions such as "Lux" are consistent across all similar entries.
437-444: Magnetic Sensor Components
The magnetic sensor block is concise and well‑formatted. Verify that images likeas5600.jpgare the correct choices for these sensors.
450-468: Miscellaneous Sensor Components Review
This section groups various sensor types under miscellaneous. Please verify that categorization is intuitive and that there are no inadvertent duplications.
483-497: Motion Sensor Components
The motion sensors are briefly listed. If components such as "APDS9960" appear in multiple sections, confirm that this duplication is intentional based on their functionality.
498-507: Thermocouple Components
Thermocouple entries are formatted correctly. Verify that images likemax31855.jpgreflect the latest visual standards.
509-517: Weight Sensor Components
The weight sensor section is minimal and clear. Ensure that the image for "HX711" is both accurate and available.
518-523: Assistance Section for ADC Guidance
The callout inviting users to check out the ADC Sensor documentation is a useful touch. Verify that the link reference (e.g.,:doc:\ADC Sensor </components/sensor/adc>``) resolves correctly in the reorganized docs.
523-539: Binary Sensor Components Introduction
The introductory text and imgtable for binary sensors are both clear and well‑organized.
541-550: Capacitive Touch Sensor Components
The imgtable for capacitive touch sensors is concise. Confirm that image sizes and paths (e.g.,cap1188.jpg) are consistent with the updated layout.
551-558: Mechanical Components Review
The mechanical section (e.g., Matrix Keypad, TM1637/TM1638) is succinct. Verify that images are current and that the grouping fits the overall design.
560-574: NFC/RFID Components Inspection
The NFC/RFID block lists all relevant devices. Please double‑check image consistency and that the descriptions meet user expectations.
575-583: Touchscreen Components
The touchscreen components are clearly itemized. Verify that the referenced images (e.g.,touch.svg) adhere to the new documentation style.
587-597: Presence Detection Components
The presence detection section introduces an imgtable with devices like "AT581X" and "DFRobot mmWave Radar." Since some devices (e.g., LD2410, LD2420) appear in other sections, ensure this categorization is intentional.
598-607: Miscellaneous Binary Sensor Components
This section covers a wide range of sensors. The consistent styling and asset usage appear correct; just confirm that the classification meets user expectations.
614-621: Alarm Control Panel Components
The alarm control panel section is brief and clear. The imgtable appears correctly formatted with appropriate icons (e.g.,alarm-panel.svg).
622-630: Audio ADC Components
The audio ADC block is concise. Verify that references such asaudio_adc.svgaccurately reflect the new documentation assets.
631-640: Audio DAC Components
This section follows the ADC pattern. Confirm that the graphic assets (e.g.,aic3204.svg) align with current branding guidelines.
641-655: Button Components
The list of button components is clear and detailed. Verify that all image assets (e.g.,restart.svg,upload.svg) are consistent and accessible.
656-672: Climate Components
The climate section is comprehensive—from core systems to specific brands like Midea. Please ensure the images and corresponding descriptions are up‑to‑date with any recent changes in product details.
673-687: Cover Components
The cover components imgtable is well‑structured, mixing both SVGs and JPGs. Confirm that the varied media formats are intentional and consistent with the overall style.
688-695: Datetime Components
The datetime section is concise with clear usage of icons likeclock-outline.svg.
696-711: Display Components
This section lists several display‑related components. Verify that each entry (e.g., "Font Renderer", "Graph", "QR Code") remains relevant and that image paths are correct.
713-737: Display Hardware Platforms
The newly added Display Hardware Platforms section includes detailed imgtable entries. Please ensure that all referenced image files (e.g.,ili9341.jpg,inkplate6.jpg) use relative paths appropriately and match the new documentation structure.
756-767: Electromechanical Components
The electromechanical section is succinct and clear. Confirm that device images likemotor.pngandmatrix_keypad.jpgmeet current documentation standards.
768-778: Energy/Solar Management
This section covers PV inverters and power supplies. Check that the imagery (e.g.,pipsolar.jpg,power.svg) is verified and that the categorization is clear.
779-786: Event Components
The event components section is brief and to the point. No issues noted.
787-798: Fan Components
The fan components are clearly itemized. Confirm that the chosen assets (e.g.,fan.svg) and layout comply with the new documentation design.
799-814: Home Assistant Components
This section highlights integration components with Home Assistant. Please verify that all icons (e.g.,home-assistant.svg) are consistent and that the references remain correct after the docs reorganization.
815-843: Light Components Review
The light components section is very comprehensive. Confirm the correctness of image paths (especially for items likergb.pngandtuya.png) and ensure the use of relative paths is consistent throughout the document.
844-847: Individually Addressable Lights Note
The added note directing users to related documentation for WS2811‑like lights is beneficial. Please verify that the cross‑reference links (e.g.,:doc:\light/esp32_rmt_led_strip``) resolve as expected.
848-856: Lock Components
The lock components section is concise and well‑structured, with proper signage for each entry.
857-866: Media Player Components
The media player section is clearly delineated. Please check that image assets (e.g.,dfplayer.svg) are correctly relocated following the reorganization.
867-874: Microphone Components
The microphone components section is brief but clear. No issues noted.
875-886: Number Components
The number components imgtable appears well‑structured. Verify that image paths (e.g.,lvgl_c_num.png) remain valid in the reorganized docs.
887-922: Output Components
This extensive section covers a variety of output components. Given the volume, please ensure that all file paths are relative (if that is now the project standard) and that the formatting is consistent across items.
923-933: Select Components
The select components block is brief and appears accurate. Confirm that the links and image references are correct.
934-943: Speaker Components
The speaker components section is clear. Verify that all image references (e.g.,speaker.svg,mixer.svg) meet updated design standards.
944-965: Switch Components Detailing
This section lists multiple switch components. Please verify that there are no inadvertent duplicates and that each image reference (e.g.,restart.svg,power_settings.svg) is correct in the context of the restructured documentation.
966-974: Text Components
The text components are succinctly presented with the appropriate use of icons. No further issues detected here.
975-995: Text Sensor Components
The comprehensive list for text sensor components is well‑formatted. Please review that all image assets and styling options (such asdark-invert) are uniformly applied.
996-1008: Time Components
The time components section is concise and appears correctly formatted with consistent icon usage.
1009-1024: Touchscreen Components (Detailed)
This section is detailed and effectively itemizes touchscreen components. Verify that image references (e.g.,lilygo_t5_47_touch.jpg) are up‑to‑date and that the overall formatting supports easy navigation.
1025-1033: Valve Components
The valve components section is minimal but clear. Ensure that the imgtable accurately reflects available component documentation.
1034-1045: Wireless Communication Components
The wireless communication section is well‑defined and excludes Wi‑Fi as noted. Please verify that the related icons and image links (e.g.,remote.svg,sim800l.jpg) are correct.
1047-1053: Miscellaneous Components
This final listing in the components section is orderly. Ensure that each of these components has corresponding documentation and that image assets are correctly located.
1062-1079: Cookbook Section Inclusion
The new Cookbook section provides helpful links to tips and recipes. Confirm that all cookbook entries (like "Lambda Magic: Tips and Tricks") have been relocated and updated in sync with the overall documentation reorganization.
1080-1085: Contributing Section
The contributing section is succinct and includes a link to the contributing guide. This addition looks good.
Description:
SSIA
Related issue (if applicable): fixes
Pull request in esphome with YAML changes (if applicable): esphome/esphome#
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
/index.rstwhen creating new documents for new components or cookbook.