docs: add user guide - #26
Conversation
WalkthroughMake it so: this change adds an mdBook-based user guide (configuration, content pages, SUMMARY) plus a GitHub Actions workflow and .gitignore entry to build and deploy the generated book. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 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: 1
🧹 Nitpick comments (4)
docs/user-guide/src/saving.md (1)
7-9: Excellent workflow documentation; minor style refinement suggested. The saving guide is clear and practical, with a helpful tip that addresses common issues preventing archive saving. The constraint checklist is comprehensive.Consider the static analysis suggestion to use "brief" instead of "short" in line 8—it strengthens the wording and is more precise for documentation contexts.
docs/user-guide/src/overview.md (1)
7-14: Excellent UI overview that serves as a perfect entry point to the documentation suite. The enumerated sections provide a logical tour through the interface, and the internal links are well-integrated, guiding readers to detailed documentation for each feature. Your descriptions are clear and user-centric.One style refinement from static analysis: line 13 suggests using a hyphen for the compound adjective "eLabFTW-compatible" to strengthen technical writing conventions. Additionally, please verify the image exists at
docs/user-guide/src/images/ui-overview.webp.docs/user-guide/src/introduction.md (1)
20-27: Refine the Windows support warning for clarity and conciseness.The phrase "Supporting very old and current operating systems" is somewhat redundant. Consider stronger phrasing: "Supporting obsolete and current operating systems at the same time is difficult..." This maintains the emphasis on the compatibility challenge without relying on the weak intensifier "very."
Apply this diff to strengthen the language:
-> Windows XP and earlier are **not supported**. Supporting very old and current +> Windows XP and earlier are **not supported**. Supporting obsolete and currentdocs/user-guide/src/installation.md (1)
76-79: Polish cross-compilation documentation for clarity and conciseness.Two improvements are suggested: (1) "cross compilation" should be hyphenated as a compound modifier ("cross-compilation"), and (2) "are not compatible" is wordier than necessary—"incompatible" is more direct.
Apply this diff to refine the language:
- Unfortunately, the `*-win7-windows-gnu` targets which in theory would allow cross compilation and are not dependent on the MSVC BuildTools, produce binaries that are not compatible with Windows 7 due to the lack of certain system libraries. + Unfortunately, the `*-win7-windows-gnu` targets which in theory would allow cross-compilation and are not dependent on the MSVC BuildTools, produce binaries that are incompatible with Windows 7 due to the lack of certain system libraries.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (13)
.gitignore(1 hunks)docs/user-guide/book.toml(1 hunks)docs/user-guide/src/SUMMARY.md(1 hunks)docs/user-guide/src/attachments.md(1 hunks)docs/user-guide/src/datetime.md(1 hunks)docs/user-guide/src/installation.md(1 hunks)docs/user-guide/src/introduction.md(1 hunks)docs/user-guide/src/keywords.md(1 hunks)docs/user-guide/src/markdown.md(1 hunks)docs/user-guide/src/metadata.md(1 hunks)docs/user-guide/src/overview.md(1 hunks)docs/user-guide/src/quickstart.md(1 hunks)docs/user-guide/src/saving.md(1 hunks)
🧰 Additional context used
🧠 Learnings (6)
📚 Learning: 2025-12-03T16:16:45.376Z
Learnt from: CR
Repo: Athemis/ELNPack PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-03T16:16:45.376Z
Learning: Applies to src/ui/components/markdown.rs : `src/ui/components/markdown.rs` implements markdown editor with toolbar, cursor-aware insertions, and text area.
Applied to files:
docs/user-guide/src/markdown.mddocs/user-guide/src/SUMMARY.md
📚 Learning: 2025-12-03T16:16:45.376Z
Learnt from: CR
Repo: Athemis/ELNPack PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-03T16:16:45.376Z
Learning: Applies to src/ui/components/keywords.rs : `src/ui/components/keywords.rs` implements keywords editor with inline edits and add-keywords modal.
Applied to files:
docs/user-guide/src/keywords.md
📚 Learning: 2025-12-03T16:16:45.376Z
Learnt from: CR
Repo: Athemis/ELNPack PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-03T16:16:45.376Z
Learning: Applies to src/logic/eln.rs : `src/logic/eln.rs` builds and writes ELN RO-Crate metadata, generates suggested archive names, and conforms to RO-Crate 1.2 and ELN File Format specification; uses pre-sanitized names from attachments; has no UI dependencies.
Applied to files:
docs/user-guide/src/quickstart.mddocs/user-guide/src/installation.mddocs/user-guide/src/introduction.md
📚 Learning: 2025-12-03T16:16:45.376Z
Learnt from: CR
Repo: Athemis/ELNPack PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-03T16:16:45.376Z
Learning: Use `cargo run` to build and launch the desktop app; use `cargo check` before pushing; use `cargo fmt` to format Rust sources (enforced style); use `cargo clippy --all-targets --all-features` to lint for warnings; use `cargo test` to run tests; use `cargo build --release` for optimized binary distribution.
Applied to files:
docs/user-guide/src/installation.md
📚 Learning: 2025-12-03T16:16:45.376Z
Learnt from: CR
Repo: Athemis/ELNPack PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-03T16:16:45.376Z
Learning: Applies to src/logic/eln.rs : For archive structure and metadata, align with ELN File Format specification: https://raw.githubusercontent.com/TheELNConsortium/TheELNFileFormat/refs/heads/master/SPECIFICATION.md
Applied to files:
docs/user-guide/src/introduction.md
📚 Learning: 2025-12-03T16:16:45.376Z
Learnt from: CR
Repo: Athemis/ELNPack PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-03T16:16:45.376Z
Learning: Applies to src/ui/components/attachments.rs : `src/ui/components/attachments.rs` implements attachments panel with list, thumbnails, inline filename editing; computes `sanitized_name` using `sanitize_component`; shows WARNING icon on sanitized mismatch; emits commands for file picking/hashing/thumbnails; sanitizes and dedupes edited names.
Applied to files:
docs/user-guide/src/attachments.md
🪛 LanguageTool
docs/user-guide/src/installation.md
[grammar] ~78-~78: Use a hyphen to join words.
Context: ...argets which in theory would allow cross compilation and are not dependent on the...
(QB_NEW_EN_HYPHEN)
[style] ~78-~78: Consider using “incompatible” to avoid wordiness.
Context: ...C BuildTools, produce binaries that are not compatible with Windows 7 due to the lack of certa...
(NOT_ABLE_PREMIUM)
docs/user-guide/src/overview.md
[grammar] ~13-~13: Use a hyphen to join words.
Context: ...rom scratch. Will be exported as eLabFTW compatible extra fields in the final ELN...
(QB_NEW_EN_HYPHEN)
docs/user-guide/src/introduction.md
[style] ~22-~22: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...rlier are not supported. Supporting very old and current > operating systems at the ...
(EN_WEAK_ADJECTIVE)
docs/user-guide/src/saving.md
[style] ~8-~8: Consider using the synonym “brief” (= concise, using a few words, not lasting long) to strengthen your wording.
Context: ...tered a title, date/time and at least a short description. Also make sure all attachm...
(QUICK_BRIEF)
🪛 markdownlint-cli2 (0.18.1)
docs/user-guide/src/markdown.md
25-25: Blank line inside blockquote
(MD028, no-blanks-blockquote)
⏰ 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). (1)
- GitHub Check: Analyze (rust)
🔇 Additional comments (8)
.gitignore (1)
29-30: Excellent addition to the ignore patterns. The mdBook build output path is appropriately positioned and follows the existing conventions for excluding generated artifacts.docs/user-guide/src/keywords.md (1)
1-12: Well-structured keywords documentation. The content is clear and actionable, the tip block provides valuable context about comma-separated imports and deduplication, and the formatting adheres to mdBook standards.Please ensure the referenced image file exists at
docs/user-guide/src/images/ui-keywords.webp.docs/user-guide/src/attachments.md (1)
1-17: Comprehensive attachments documentation. The step-by-step guide effectively walks through the attachment workflow, and the tip block clearly explains the dual-hashing integrity feature. The writing is clear and user-focused.Please verify that the image file exists at
docs/user-guide/src/images/ui-file-attachments.webp.docs/user-guide/src/metadata.md (1)
1-21: Thorough metadata documentation with excellent visual-textual integration. The content flows logically from basic operations to advanced field properties editing, and the tip about field type immutability is crucial information for users. The numbered annotations align well with the image references.Please verify that both referenced images exist:
docs/user-guide/src/images/ui-metadata-overview.webpanddocs/user-guide/src/images/ui-metadata-edit-field.webp. Also confirm the internal link format at line 4 works correctly with your mdBook setup.docs/user-guide/book.toml (1)
1-8: Clean and appropriate mdBook configuration. The title accurately reflects the project, authors attribution is present, and the theme selections (light default with ayu dark theme) provide a pleasant user experience.docs/user-guide/src/SUMMARY.md (1)
1-12: Well-organized table of contents structure. The hierarchy properly reflects the documentation organization, with UI subsections appropriately nested under the UI Overview section. The file path format follows mdBook conventions.docs/user-guide/src/quickstart.md (1)
1-12: Well-structured workflow guide that provides clear, actionable steps.The progression from launching the application through saving the archive is logical and accessible. Cross-references to related documentation sections are appropriately placed to support users without overwhelming them with inline details. The emphasis on offline operation and import compatibility is a thoughtful touch for the target user base.
docs/user-guide/src/datetime.md (1)
1-11: Concise documentation of the Date & Time Picker feature.The guide clearly explains the picker's capabilities and storage behavior. The tip about backfilling older experiments is practical guidance that acknowledges a common use case. Image placement and admonition formatting follow mdBook conventions correctly.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/user-guide/src/markdown.md (1)
21-26: Engage: We must resolve the markdown blockquote formatting violation that persists.It appears the blank line within the [!TIP] blockquote—which was previously flagged—remains unaddressed. A blank line inside the blockquote at line 24 violates the MD028 markdown linting rule, disrupting proper blockquote rendering and formatting consistency.
Apply this diff to eliminate the unnecessary blank line and restore formatting integrity:
> [!TIP] -> > - You can use all features of [CommonMark](https://commonmark.org) with some additional Markdown extensions like tables and math. > - Use raw HTML in the Markdown code for more advanced formatting. Keep in mind though that HTML is sanitized when exporting the ELN archive to prevent XSS attacks which may remove **potentially unsafe** HTML tags (e.g., `<script>`).This ensures the blockquote structure remains cohesive and compliant with markdown best practices, much like maintaining proper command protocols aboard a starship.
🧹 Nitpick comments (2)
.github/workflows/mdbook.yml (2)
32-34: Consider adding Cargo cache to accelerate workflow execution.The workflow reinstalls mdBook on every run via
cargo install. Since mdBook is a stable external tool, caching the Cargo build artifacts would accelerate subsequent workflow executions—particularly valuable if you trigger deployments frequently.Here's a suggested enhancement to add Cargo caching:
- name: Checkout uses: actions/checkout@v6 + - name: Cache Cargo + uses: Swatinem/rust-cache@v2 - name: Install mdBook run: | cargo install --version ${MDBOOK_VERSION} mdbook
38-43: Consider adding an explicit verification step after the mdBook build.Your workflow builds the documentation and uploads the artifact without explicitly verifying that the build succeeded or that the output directory exists. While GitHub Actions will fail the step if the build fails, adding an explicit verification step would enhance clarity and provide better diagnostics if something goes awry.
Here's an optional enhancement to add explicit verification:
- name: Build with mdBook run: mdbook build docs/user-guide + - name: Verify build output + run: | + if [ ! -d "docs/user-guide/book" ]; then + echo "Error: mdBook build did not produce the expected output directory" + exit 1 + fi - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: docs/user-guide/book
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.github/workflows/mdbook.yml(1 hunks)docs/user-guide/src/markdown.md(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-03T16:16:45.376Z
Learnt from: CR
Repo: Athemis/ELNPack PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-03T16:16:45.376Z
Learning: Applies to src/ui/components/markdown.rs : `src/ui/components/markdown.rs` implements markdown editor with toolbar, cursor-aware insertions, and text area.
Applied to files:
docs/user-guide/src/markdown.md
🪛 markdownlint-cli2 (0.18.1)
docs/user-guide/src/markdown.md
24-24: Blank line inside blockquote
(MD028, no-blanks-blockquote)
⏰ 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). (1)
- GitHub Check: Analyze (rust)
🔇 Additional comments (1)
.github/workflows/mdbook.yml (1)
1-55: Make it so: Your GitHub Pages deployment workflow is well-structured and properly configured.The workflow elegantly separates build and deploy responsibilities, appropriately scopes permissions for GitHub Pages, and maintains consistent path references throughout. The use of concurrency controls with
cancel-in-progress: falseensures production deployments complete uninterrupted.
| env: | ||
| MDBOOK_VERSION: 0.5 |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
latest stable version of mdBook release
💡 Result:
Latest stable mdBook release: v0.5.1 (released Nov 20, 2025). (github.com)
Citations:
mdBook version 0.5 is outdated; consider updating to v0.5.1.
The workflow pins MDBOOK_VERSION: 0.5, but the latest stable release is v0.5.1 (released Nov 20, 2025). Update to the latest patch version unless there is a specific reason to stay on an older release. Additionally, consider documenting why this version was chosen for future maintainers.
🤖 Prompt for AI Agents
.github/workflows/mdbook.yml lines 27-28: the workflow pins MDBOOK_VERSION to
0.5 which is outdated; update the MDBOOK_VERSION value to 0.5.1 (the latest
patch) in the env block and, if applicable, update any workflow steps or
comments that reference the version; also add a short inline comment or
workflow-level note documenting why 0.5.1 was chosen (or add a link to the
release notes) so future maintainers understand the decision.
1 participant
Summary
Testing
cargo fmtcargo clippy --all-targets --all-featurescargo testcargo doc --no-depsPlatforms exercised (mark all that apply):
Screenshots (if UI changes)
Manual test steps (if UI or IO)
Docs/metadata
Notes for reviewers
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.