docs: refresh README (AI-assisted) - #942
Conversation
github-actions
Bot
added
size/medium
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughREADME.md was reorganized as a structured landing page for the Armbian Documentation repository. It now documents the repository layout, published documentation, local MkDocs setup, file-naming conventions, configuration regeneration, GitHub Actions workflows, contribution guidance, and GPL v3 licensing. The header adds branding and documentation links, while setup and automation instructions are organized into dedicated sections. Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Around line 24-33: Specify a language on both fenced code blocks in the README
repository-tree examples, including the additional fence around lines 43–45. Use
text or another appropriate language identifier while preserving the existing
contents.
- Around line 94-99: Update the README’s mkdocs serve command to bind the local
preview to 127.0.0.1:8000 instead of 0.0.0.0:8000, and mention the broader
0.0.0.0 binding only as an intentional option for remote access.
- Around line 41-47: Update the argparse help text in tools/mkArmbianDocs.py to
describe the parser’s underscore-separated filename convention, using the
[Parent-Topic]_[Child-Topic]-example.md format instead of
[ParentCategory]-Subtopic.md. Keep the README convention and parser behavior
unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| ### File naming convention | ||
|
|
||
| ``` | ||
| [Parent-Topic]_[Child-Topic]-example.md | ||
| ``` | ||
|
|
||
| Parent and child topics are separated by an underscore (`_`). Hyphens (`-`) are automatically converted to spaces when rendered. Please avoid creating new parent topics unless absolutely necessary. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
rg -n 'ParentCategory|Parent-Topic|split|findFiles|parseFiles' README.md tools/mkArmbianDocs.pyRepository: armbian/documentation
Length of output: 657
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== README excerpt ==\n'
sed -n '38,50p' README.md
printf '\n== tools/mkArmbianDocs.py excerpt ==\n'
nl -ba tools/mkArmbianDocs.py | sed -n '1,120p'Repository: armbian/documentation
Length of output: 659
🏁 Script executed:
#!/bin/bash
set -euo pipefail
nl -ba tools/mkArmbianDocs.py | sed -n '1,120p'Repository: armbian/documentation
Length of output: 199
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== tools/mkArmbianDocs.py (1-240) ==\n'
awk '{printf "%4d %s\n", NR, $0}' tools/mkArmbianDocs.py | sed -n '1,240p'
printf '\n== search for filename handling ==\n'
grep -nE 'split|replace|Parent|Child|Category|Subtopic|example' tools/mkArmbianDocs.pyRepository: armbian/documentation
Length of output: 7411
Align the generator help text with the parser contract. tools/mkArmbianDocs.py already accepts underscore-separated names like [Parent-Topic]_[Child-Topic]-example.md; the argparse description still says [ParentCategory]-Subtopic.md, which is misleading for contributors.
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 43-43: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 41 - 47, Update the argparse help text in
tools/mkArmbianDocs.py to describe the parser’s underscore-separated filename
convention, using the [Parent-Topic]_[Child-Topic]-example.md format instead of
[ParentCategory]-Subtopic.md. Keep the README convention and parser behavior
unchanged.
| ```bash | ||
| mkdocs build --clean | ||
| mkdocs serve -a 0.0.0.0:8000 | ||
| ``` | ||
|
|
||
| Then open your browser and go to http://localhost:8000 | ||
| The site will automatically reload when you make changes to .md files. | ||
| Then open [http://localhost:8000](http://localhost:8000). The site auto-reloads when `.md` files change. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win
Bind the local preview to localhost by default.
0.0.0.0:8000 exposes unpublished documentation to every reachable network interface. Use 127.0.0.1:8000 for a local-preview instruction, and document the broader bind only for intentional remote access.
Proposed fix
-mkdocs serve -a 0.0.0.0:8000
+mkdocs serve -a 127.0.0.1:8000📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```bash | |
| mkdocs build --clean | |
| mkdocs serve -a 0.0.0.0:8000 | |
| ``` | |
| Then open your browser and go to http://localhost:8000 | |
| The site will automatically reload when you make changes to .md files. | |
| Then open [http://localhost:8000](http://localhost:8000). The site auto-reloads when `.md` files change. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 94 - 99, Update the README’s mkdocs serve command to
bind the local preview to 127.0.0.1:8000 instead of 0.0.0.0:8000, and mention
the broader 0.0.0.0 binding only as an intentional option for remote access.
a2f22aa to
3d87160
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Around line 98-100: Update the README filename example to use the same
Child-Topic-Name placeholder described in the surrounding naming guidance,
keeping the underscore separator and hyphen-rendering explanation unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
c8a17a7 to
e345d4f
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 42: Update the GitHub link in the README contribution sentence to point
to the repository’s GitHub URL instead of the local docs/ directory, while
leaving the surrounding MkDocs preview instructions unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
e345d4f to
26bda9d
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 43: Update the filename guidance in README.md to state that only the
first three hyphens in each parent and child topic are converted to spaces,
matching tools/mkArmbianDocs.py; do not change the generator behavior.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| [Parent-Topic]_[Child-Topic]-example.md | ||
| ``` | ||
|
|
||
| Parent and child topics are separated by an underscore (`_`). Hyphens (`-`) are automatically converted to spaces in the rendered navigation. Please avoid creating new parent topics unless strictly necessary. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Align the filename guidance with tools/mkArmbianDocs.py.
The generator converts only the first three hyphens in each parent and child topic. Line 43 says that all hyphens are converted. Document the limit, or change the generator to replace all hyphens.
Proposed README fix
-Parent and child topics are separated by an underscore (`_`). Hyphens (`-`) are automatically converted to spaces in the rendered navigation. Please avoid creating new parent topics unless strictly necessary.
+Parent and child topics are separated by an underscore (`_`). The first three hyphens in each topic are converted to spaces in the rendered navigation. Please avoid creating new parent topics unless strictly necessary.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Parent and child topics are separated by an underscore (`_`). Hyphens (`-`) are automatically converted to spaces in the rendered navigation. Please avoid creating new parent topics unless strictly necessary. | |
| Parent and child topics are separated by an underscore (`_`). The first three hyphens in each topic are converted to spaces in the rendered navigation. Please avoid creating new parent topics unless strictly necessary. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` at line 43, Update the filename guidance in README.md to state
that only the first three hyphens in each parent and child topic are converted
to spaces, matching tools/mkArmbianDocs.py; do not change the generator
behavior.
26bda9d to
b2a1d1c
Compare
b2a1d1c to
8852d30
Compare
1 participant
Automated README refresh generated by the Maintenance: Update README (AI)
workflow in
armbian.github.io.The content is generated by Claude from this repository's own files (file tree,
manifests, workflows, existing README). Please review for accuracy before
merging — edit or close if anything is wrong.
Leave review comments here: while this PR stays open, the next run reads them
and folds your fixes into the regenerated README (they won't be overwritten).
Documentation website preview will be available shortly:
Open WWW preview