Migrate HAOS docs from the OS repo #2748
Conversation
Move documentation from the OS repository to the developer docs. All of the docs tracked in the repo were generally developer-facing and some information was documented here, some in the repo. As the first step, move all the docs as-is with only the links modified and structure adjusted for the rendered docs, without further proofreading or checks (TBD later).
Move all documentation (except the kernel.md, for which it makes sense to be kept here) to developers.home-assistant.io. Just bluetooth.md was intentionally not preserved, as the information value was low and it was out of date anyway. See home-assistant/developers.home-assistant#2748
📝 WalkthroughWalkthroughThis change introduces a comprehensive set of new documentation files for various hardware boards and operating system configuration topics. It also updates the sidebar configuration to organize and surface these new docs, including board-specific guides, OS configuration, and network setup instructions. No code or public API changes are included. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
✨ Finishing Touches
🧪 Generate unit tests
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. 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: 1
🧹 Nitpick comments (22)
docs/operating-system/boards/asus.md (1)
22-28: Fix grammar, spelling, and fenced-block language hint• Line 22 – missing “to” before “maskrom mode”.
• Line 24 – “Continusly” → “Continuously”.
• Line 27 – code fence lacks a language identifier (MD040 violation).-1. Set the jumper between Micro-USB and HDMI the maskrom mode -3. Continusly press Ctrl+C to interrupt boot -``` +1. Set the jumper between Micro-USB and HDMI to maskrom mode +3. Continuously press Ctrl+C to interrupt boot +```bashdocs/operating-system/boards/ova.md (1)
23-24: Typo in requirements list“Minimal of 1GB RAM” → “Minimum of 1 GB RAM”.
-- Minimal of 1GB RAM +- Minimum of 1 GB RAMdocs/operating-system/network.md (2)
19-21: Add language identifier to code blockThe fenced block opened on Line 19 lacks a language hint, triggering MD040.
-``` +```bash
136-140: Typo: “us” → “use”Line 136: “…you can us the
ha networkcommand…” should read “…you can use theha networkcommand…”.- Wi-Fi is discouraged for reliability reasons. However, if you still prefer to use Wi-Fi, you can us the `ha network` + Wi-Fi is discouraged for reliability reasons. However, if you still prefer to use Wi-Fi, you can use the `ha network`docs/operating-system/boards/generic-aarch64.md (1)
23-29: Consistent spelling of Wi-FiUse the standard “Wi-Fi” spelling to match other docs.
-## Wifi +## Wi-Fidocs/operating-system/boards/odroid-c4.md (2)
10-15: Use extension-less links for intra-doc referencesLinks such as
[ODROID-C2](./odroid-c2.md)and[Odroid-N2](./odroid-n2.md)include the.mdextension. Docusaurus resolves these, but omitting the extension (e.g../odroid-c2) is the recommended, future-proof style adopted elsewhere in the docs set.
12-15: Capitalize proper nouns consistentlyLine 12 bullet list mixes “eMMC”/“MAC”/“SD” with “boot”/“boot”. Consider capitalising “Boot from SD” and “Boot from eMMC” for visual consistency with the other items.
docs/operating-system/boards/odroid-n2.md (1)
12-14: Grammar & style tweaks for clarity
eg.→e.g.,and consider replacing “plan on using” → “intend to use” for a slightly more formal tone.-eg. `console=ttyAML0,115200n8 console=tty0` +e.g., `console=ttyAML0,115200n8 console=tty0`- ...if you don't plan on using the serial adapter. + ...if you do not intend to use the serial adapter.docs/operating-system/boards/odroid-c2.md (1)
12-14: Apply the same grammar fixes as in the N2 documentSee previous comment: use
e.g.,and replace “plan on using” with “intend to use” for consistency across board docs.docs/operating-system/boards/overview.md (1)
42-44: Fix list indentation under “Notes” to satisfy markdownlintIndentation is two spaces instead of none, triggering MD007. Removing the extra spaces also renders the list correctly.
-Notes: - - see ? above: are these currently supported? see ova documentation which explains issues with previous OVA distribution) +Notes: +- See “?” above — these formats are currently unverified. Refer to the OVA documentation for details about historic issues.docs/operating-system/boards/generic-x86-64.md (2)
19-19: Replace hard tab with spaces.A literal tab character sneaked into the “Intel NUC7i3DNHE” table row. Tabs break table alignment in many Markdown renderers.
-| Intel NUC7i3DNHE | Q3 2017 | yes | … +| Intel NUC7i3DNHE | Q3 2017 | yes | …
33-34: Convert bare URL to Markdown link for consistency.The out-of-tree driver URL is rendered bare and triggers MD034. Use normal link syntax:
- - Intel PCIe Gigabit NIC (e1000e - via out-of-tree module in *https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/package/intel-e1000e*) + - Intel PCIe Gigabit NIC – [e1000e out-of-tree module](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/package/intel-e1000e)docs/operating-system/boards/odroid-xu4.md (1)
16-16: Fix typo “corruped” → “corrupted”.-2. **Not Working** e.g. a clean/wiped/corruped eMMC boot partition: +2. **Not Working** e.g. a clean/wiped/corrupted eMMC boot partition:docs/operating-system/boards/odroid-m1.md (2)
21-22: Insert missing space after “to”.-4. Rename the `spiboot-20240109.img` file to`spiboot.img`. +4. Rename the `spiboot-20240109.img` file to `spiboot.img`.
40-41: Grammar: “tries searches” → “tries to search” (or simply “searches”).-The SPI flashed U-Boot SPL tries searches for an U-Boot binary on the SD-card +The SPI-flashed U-Boot SPL searches for a U-Boot binary on the SD carddocs/operating-system/boards/odroid-m1s.md (1)
17-20: Correct tool name typo.
balenaEtcherlost its “c”.-4. The eMMC will show as a drive on your PC and you can directly flash the HAOS image with balenaEther. +4. The eMMC will show as a drive on your PC and you can flash the HAOS image with balenaEtcher.docs/operating-system/boards/raspberrypi.md (2)
24-27: Specify language for fenced code block (MD040).-``` +i2c i2c-dev i2c-bcm2708 -``` +```
51-52: Minor grammar tweak.-If you don't need bluetooth, disabled it with add `dtoverlay=pi3-disable-bt` into `config.txt`. +If you don’t need Bluetooth, disable it by adding `dtoverlay=pi3-disable-bt` to `config.txt`.docs/operating-system/configuration.md (4)
8-10: Fix article usage and wording for clarityMinor language issues reduce the professionalism of the docs.
-You can use an USB drive with HassOS to configure network options, SSH access to the host and to install updates. -Format a USB stick with FAT32/EXT4/NTFS and name it `CONFIG` (in all capitals). Alternative you can create a `CONFIG` folder inside the `boot` partition. Use the following directory structure within the USB drive: +You can use a USB drive with Home Assistant OS to configure network options, enable SSH access to the host, and install updates. +Format a USB stick with FAT32/EXT4/NTFS and name it `CONFIG` (all capitals). Alternatively, you can create a `CONFIG` folder inside the `boot` partition. Use the following directory structure on the USB drive:
26-29: Grammar & factual accuracy tweaks in bullets-- The `timesyncd.conf` file allow you to set different NTP servers. HassOS won't boot without correct working time servers! +- The `timesyncd.conf` file allows you to set alternative NTP servers. Accurate time synchronisation is required; otherwise some services may fail to start correctly. -- The `hassos-*.raucb` file is a firmware OTA update which will be installed. These can be found on on the [release][hassos-release] page. +- The `hassos-*.raucb` file is a firmware OTA update that will be installed automatically. These files can be found on the [release][hassos-release] page. -Text files that are on USB stick must have Unix (LF) end of line characters. +Text files on the USB stick must use Unix (LF) line endings.
57-61: Add language identifier to fenced code block (MD040)Static-analysis flagged this block; specifying
inisatisfies MD040 and gives readers syntax highlighting.-``` +```ini [Time] NTP=time.cloudflare.com FallbackNTP=0.pool.ntp.org 1.pool.ntp.org 2.pool.ntp.org 3.pool.ntp.org--- `49-55`: **Minor grammar adjustments in “Network” and “NTP” sections** ```diff -You can manual add, edit or remove connections configurations from `/etc/NetworkManager/system-connections`. +You can manually add, edit, or remove connection configurations in `/etc/NetworkManager/system-connections`. -You can manual edit the systemd timesync file on `/etc/systemd/timesyncd.conf`. +You can manually edit the systemd timesync file at `/etc/systemd/timesyncd.conf`. -Our default NTP configuration look like: +The default NTP configuration looks like this:
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting
📒 Files selected for processing (16)
docs/operating-system/boards/asus.md(1 hunks)docs/operating-system/boards/generic-aarch64.md(1 hunks)docs/operating-system/boards/generic-x86-64.md(1 hunks)docs/operating-system/boards/hardkernel.md(1 hunks)docs/operating-system/boards/odroid-c2.md(1 hunks)docs/operating-system/boards/odroid-c4.md(1 hunks)docs/operating-system/boards/odroid-m1.md(1 hunks)docs/operating-system/boards/odroid-m1s.md(1 hunks)docs/operating-system/boards/odroid-n2.md(1 hunks)docs/operating-system/boards/odroid-xu4.md(1 hunks)docs/operating-system/boards/ova.md(1 hunks)docs/operating-system/boards/overview.md(1 hunks)docs/operating-system/boards/raspberrypi.md(1 hunks)docs/operating-system/configuration.md(1 hunks)docs/operating-system/network.md(1 hunks)sidebars.js(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
docs/operating-system/boards/asus.md
27-27: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/operating-system/boards/overview.md
43-43: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
docs/operating-system/network.md
19-19: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/operating-system/boards/generic-x86-64.md
19-19: Hard tabs
Column: 19
(MD010, no-hard-tabs)
33-33: Bare URL used
(MD034, no-bare-urls)
docs/operating-system/boards/raspberrypi.md
24-24: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/operating-system/configuration.md
19-19: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🪛 LanguageTool
docs/operating-system/boards/odroid-xu4.md
[grammar] ~16-~16: Ensure spelling is correct
Context: ...) 2. Not Working e.g. a clean/wiped/corruped eMMC boot partition: - You'll need t...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~27-~27: Try using a more formal synonym here to elevate your writing.
Context: ...so delete the SAC2 console if you don't plan on using the serial adapter. eg. `console=tty1 c...
(PLAN_ON_INTEND)
docs/operating-system/network.md
[style] ~181-~181: This phrase is redundant (‘S’ stands for ‘system’). Use simply “DNS”.
Context: ... you are using Pi-Hole or a third-party DNS system then you can set the DNS server to that...
(ACRONYM_TAUTOLOGY)
[locale-violation] ~188-~188: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ...nmcli> save you will save the changes afterwards. If you now view the default connectio...
(AFTERWARDS_US)
docs/operating-system/boards/odroid-m1s.md
[style] ~10-~10: As a shorter alternative for ‘able to’, consider using “can still”.
Context: ...actory-default U-Boot SPL loader, which is still able to load U-Boot provided in the HAOS image....
(BE_ABLE_TO)
[style] ~21-~21: Consider using “incompatible” to avoid wordiness.
Context: ...ge anymore, because the mainline SPL is not compatible with U-Boot in the EMMC2UMS image at th...
(NOT_ABLE_PREMIUM)
[style] ~23-~23: Consider a more expressive alternative.
Context: ... to use HAOS booted from an SD card. To do that, insert the SD card with HAOS to t...
(DO_ACHIEVE)
docs/operating-system/boards/odroid-n2.md
[style] ~12-~12: Try using a more formal synonym here to elevate your writing.
Context: ...so delete the AML0 console if you don't plan on using the serial adapter. eg. `console=ttyAML...
(PLAN_ON_INTEND)
docs/operating-system/boards/odroid-c2.md
[style] ~12-~12: Try using a more formal synonym here to elevate your writing.
Context: ...so delete the AML0 console if you don't plan on using the serial adapter. eg. `console=ttyAML...
(PLAN_ON_INTEND)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - developers-home-assistant
- GitHub Check: Header rules - developers-home-assistant
- GitHub Check: Pages changed - developers-home-assistant
🔇 Additional comments (1)
docs/operating-system/boards/hardkernel.md (1)
8-16: Board table looks goodTable structure, links, and metadata render correctly.
| "operating-system/deployment", | ||
| "operating-system/update-system", | ||
| { | ||
| type: "category", | ||
| label: "Board-specific documentation", |
There was a problem hiding this comment.
This makes the sidebar wider then necessary, maybe simply:
| label: "Board-specific documentation", | |
| label: "Board support", |
There was a problem hiding this comment.
Does it? For me it still fits in the rendered docs in the width of the sidebar, it's the same width as on production.
There was a problem hiding this comment.
The sidebar is actually a fixed width, the text breaks if it's too long, as can be seen at https://developers.home-assistant.io/docs/android/ci
| @@ -0,0 +1,66 @@ | |||
| --- | |||
| title: "Home Assistant Operating System configuration" | |||
| sidebar_label: OS Configuration | |||
There was a problem hiding this comment.
Since this is already under Operating System, "OS" is duplication here:
| sidebar_label: OS Configuration | |
| sidebar_label: Configuration |
There was a problem hiding this comment.
Hmm, my thought process was to highlight it's really OS configuration, not e.g. dev environment, but whatever.
There was a problem hiding this comment.
OS doesn't really help a lot to clarify what type of configuration we are talking here, e.g. my initial thought was that this describes the build time operating system configuration (as in Buildroot defconfig) since it is the developer documentation 🤷 .
But that is a general problem that the remaining docs we had in the OS repo was mostly user focused.
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
* Migrate docs to developers.home-assistant.io Move all documentation (except the kernel.md, for which it makes sense to be kept here) to developers.home-assistant.io. Just bluetooth.md was intentionally not preserved, as the information value was low and it was out of date anyway. See home-assistant/developers.home-assistant#2748 * Fix reference links
Proposed change
Move documentation from the OS repository to the developer docs. All of the docs tracked in the repo were generally developer-facing and some information was documented here, some in the repo.
As the first step, move all the docs as-is with only the links modified and structure adjusted for the rendered docs, without further proofreading or checks (TBD later).
Type of change
Checklist
Additional information
Summary by CodeRabbit