Manual

[SteveMicroNova]

What does this change intend to accomplish?

• Making an updated manual for compliance, with new images and QR code links to this repo for forward compatibility even in printed format

Checklist

• [x] Have you checked to ensure there aren't other open Pull Requests for the same update/change?
• [x] If applicable, have you updated the documentation/manual?
• [x] Does the manual build?

When reviewing this PR, ctrl+F for "EDIT EDIT EDIT" to find spots where I specifically needed clarification/opinions on

[SteveMicroNova]

QR Codes generated using this program: https://new.express.adobe.com/tools/generate-qr-code

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Comparison is base (8625571) 50.90% compared to head (c1e1f5f) 50.90%. Report is 1 commits behind head on main.

:exclamation: Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #615   +/-   ##
=======================================
  Coverage   50.90%   50.90%           
=======================================
  Files          25       25           
  Lines        5663     5663           
=======================================
  Hits         2883     2883           
  Misses       2780     2780           

Flag	Coverage Δ
unittests	50.90% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[SteveMicroNova]

Just gonna bulk request review so everyone can look over this and give feedback, no timetable required for these requests

[klay2000]

The script to build the manual doesn't work anymore, it looks like LaTeX just doesn't like SVGs. At least a couple of the problem files are QR codes, and out of curiosity I checked and there's a LaTeX package for making QR codes that you might consider looking into. https://tex.stackexchange.com/questions/1429/latex-package-to-generate-qr-codes

[linknum23]

Was this tested? The markdown->latex transpiler has a rather strict bunch of constraints on how the markdown needs to be written.

[SteveMicroNova]

We just said this in person but to document it here as well: I've been bouncing between various internal projects as well as this manual, I'm actually a few weeks removed from the most recent addition to this branch currently. I have not tested the creation script and have only gotten as far as installing docker and not much else as far as the sewing together of the manual pages goes

I just wanted to request review for a more copy editor form of review, not a rubber stamp and deploy type of review

[Lohrer]

The script to build the manual doesn't work anymore, it looks like LaTeX just doesn't like SVGs.

LaTeX is perfectly capable of handling SVGs, but it looks like the markdown conversion isn't working right for ![url](img.svg). This minimal example works perfectly fine in LaTeX on my computer (with inkscape installed):

\documentclass{article}
\usepackage{svg}
\begin{document}
\begin{figure}[htbp]
  \centering
  \includesvg{imgs/manual/sonoff-user-manual-qr}
  \caption{https://sonoff.tech/wp-content/uploads/2023/11/Quick-Guide\_NSPanel-US-V1.4.pdf}
\end{figure}
\end{document}

With latexmk not handling SVGs correctly I'd recommend replacing them with something supported, unless some workaround exists. That'll be really sad, vectors are nice...

[linknum23]

Oddly svgs work fine in the earlier version of latexmk installed on my computer (via docker).

On Tue, Jan 9, 2024 at 11:58 AM Michael Lohrer @.***> wrote:

The script to build the manual doesn't work anymore, it looks like LaTeX just doesn't like SVGs.

LaTeX is perfectly capable of handling SVGs, but it looks like the markdown conversion isn't working right for . This minimal example works perfectly fine in LaTeX on my computer (with inkscape installed):

\documentclass{article}\usepackage{svg}\begin{document}\begin{figure}[htbp] \centering \includesvg{imgs/manual/sonoff-user-manual-qr} \caption{https://sonoff.tech/wp-content/uploads/2023/11/Quick-Guide_NSPanel-US-V1.4.pdf}\end{figure}\end{document}

With latexmk not handling SVGs correctly I'd recommend replacing them with something supported, unless some workaround exists. That'll be really sad, vectors are nice...

— Reply to this email directly, view it on GitHub https://github.com/micro-nova/AmpliPi/pull/615#issuecomment-1883430342, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAEZPO7PJ7QHAMWHHMHGRADYNVZJVAVCNFSM6AAAAABBR5RIW6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQOBTGQZTAMZUGI . You are receiving this because your review was requested.Message ID: @.***>

[SteveMicroNova]

There's an impending merge error according to Github The issue is that someone changed one line of QUICK_START.md to have slightly different wording It's an error because that file is moved entirely now, and can't merge that change easily I'll add that wording change manually and then once this is approved we may force push to main or something to get it to be chill

[linknum23]

Squash all of your changes then rebase on main?

On Wed, Mar 20, 2024 at 3:44 PM SteveMicroNova @.***> wrote:

There's an impending merge error according to Github The issue is that someone changed one line of QUICK_START.md to have slightly different wording It's an error because that file is moved entirely now, and can't merge that change easily I'll add that wording change manually and then once this is approved we may force push to main or something to get it to be chill

— Reply to this email directly, view it on GitHub https://github.com/micro-nova/AmpliPi/pull/615#issuecomment-2010485564, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAEZPO2OVQOYKCSML2UJ2O3YZHRKVAVCNFSM6AAAAABBR5RIW6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMJQGQ4DKNJWGQ . You are receiving this because you were mentioned.Message ID: @.***>

[linknum23]

I am vehemently opposed to committing a generated PDF. Add it to the .gitignore and rebase and squash this.

[linknum23]

For including the manual we should add it as a build artifact in the release.

[rtertiaer]

to surface an IRL conversation here, we're gonna omit the compiled PDF from this PR, squash all the commits, and fast follow with hosting the rendered version, perhaps with a github workflow.

[SteveMicroNova]

To reflect IRL happenings: I handed Jason a printed version of the manual, he handed it back to me with written review This will be continued soon