docs: refresh README (AI-assisted) - #942
Conversation
github-actions
Bot
added
size/medium
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 workflow badges, 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 docstrings
🧪 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
3d87160 to
c8a17a7
Compare
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
|
|
||
| ## Contributing | ||
|
|
||
| You can contribute directly on [GitHub](docs/) by editing files or submitting pull requests. For a fully rendered local preview with proper styling and live reload, set up MkDocs locally as shown below. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Fix the “GitHub” link target.
[GitHub](docs/) resolves to the repository’s local docs/ directory, not GitHub. Link to the repository URL so contributors reach the intended contribution location.
🤖 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 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.
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