FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Add ORNLSlicer user guide by aroschli · Pull Request #243 · ORNLSlicer/ORNLSlicer · GitHub

Add ORNLSlicer user guide - #243

Draft
aroschli wants to merge 26 commits into
developfrom
docs/add-new-user-manual
Draft

Add ORNLSlicer user guide#243
aroschli wants to merge 26 commits into
developfrom
docs/add-new-user-manual

Conversation

Copy link
Copy Markdown
Collaborator

Summary

  • Add the new canonical ORNLSlicer user guide Markdown source and generated PDF/manual links.
  • Add a generated detailed settings reference sourced from resources/settings/*.yaml and resources/configs/setting_inputs.conf.
  • Add scripts/generate_settings_reference.py for regenerating and checking the manual appendix.
  • Add a Pandoc Lua filter so diagram-placeholder callouts render in red in generated PDF/HTML output.

Why

This gives users and release packages a single structured manual for GUI, CLI, settings, slicing, G-code, projects, preferences, and troubleshooting workflows. The settings appendix is generated so it stays aligned with the canonical settings metadata.

Validation

  • python3 -B scripts/generate_settings_reference.py --check
  • git diff --check
  • settings YAML parse
  • resources/configs/master.conf JSON parse
  • python3 -m py_compile scripts/generate_settings_reference.py

Note: I could not regenerate the PDF after adding the placeholder-color filter in this environment because Pandoc/LaTeX are not installed, and the temporary Nix toolchain path attempted a very large bootstrap build.

Copy link
Copy Markdown
Collaborator Author

Update on the follow-up changes now included in this draft PR:

  • Added the canonical Markdown user guide plus the generated PDF, and switched docs links toward the Markdown source so the manual is easier to review and maintain.
  • Added scripts/generate_settings_reference.py to keep the settings appendix generated from resources/settings/*.yaml and resources/configs/setting_inputs.conf, with updated settings metadata/tooltips feeding that reference.
  • Added the User Guide workflow so CI regenerates the settings catalog/manual, uploads the generated PDF artifact, verifies deterministic generated sources, and refreshes the committed PDF on branch pushes when guide inputs change.
  • Added Pandoc support for release PDF generation, including the Lua filter/header that colors diagram-placeholder callouts red in PDF/HTML output.
  • Fixed Help > User Guide so it can find installed/source documentation, prefers opening the PDF with a real external viewer, and falls back to an in-app Markdown guide when the system has no default PDF application.
  • Improved the in-app guide fallback with working table-of-contents links, explicit anchor mapping, red placeholder styling, search, and Back/Forward navigation between clicked guide locations.
  • Added replaceable guide images in docs/user-guide-images/figure01.png through figure64.png using Git LFS, inserted those image references before the placeholder notes, documented the replacement workflow, and installed the image folder beside the guide. Replacing one of those files and regenerating the guide updates both the Markdown fallback and PDF.

Validation performed locally:

  • python3 -B scripts/generate_settings_reference.py --check
  • git diff --check
  • image-reference check: 64 refs, 64 image files, sequential numbering, no missing image files
  • nix develop -c cmake --build build/generic-llvm-ninja --target ornlslicer -j 2
  • nix develop -c cmake --install build/generic-llvm-ninja --config Debug --prefix /tmp/ornlslicer-user-guide-install-test

Current PR head: 269ffb81. CI is green for the guide workflow, Ubuntu, macOS, Linux, and Windows as of this comment.

liamnwhite1 force-pushed the docs/add-new-user-manual branch 3 times, most recently from d0f9d27 to 43d7dfa Compare August 24, 2026 17:19
aroschli and others added 25 commits August 25, 2026 08:06
- Replaced the ORNLSlicer User Guide PDF with a new version (size reduced from 2,199,266 to 2,126,694 bytes).
- Updated the link in the Home.md documentation to point to the ORNLSlicer User Guide in Markdown format instead of PDF.
- Revised tooltips for thermal scanner, auto speed ramping, file output, and cross-sectioning settings to provide clearer descriptions of their functionality and limitations.
- Introduced a new script, `generate_settings_reference.py`, to automate the generation of a detailed settings appendix for the ORNLSlicer user guide, ensuring consistency and accuracy in documentation.
- Enhanced the README to include instructions for regenerating the settings reference after changes to the YAML files.
liamnwhite1 force-pushed the docs/add-new-user-manual branch from 43d7dfa to 9bd3294 Compare August 25, 2026 12:06
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants


Back | FazBrowse Home | New Git URL