add example wiring diagram

[mrbojangles3]

also experiment with adding line numbers for listings

[github-actions]

🚀 Deployed on https://preview-77--hedgehog-docs.netlify.app

[qmonnet]

Please find some small suggestions below.

Why is your commit title “initial commit”?

[mrbojangles3]

The commit message is because I was rushing, I will change it.

[pau-hedgehog]

1. Can also use mac: 34:AD:61:00:02:03 is confusing.

You could take the opportunity to refer to the line number instead, now that you are introducing them

I pushed a commit fixing a small typo.

Probably on another PR:

• We should refer to the hhfab validate to ensure the wiring YAML is correct
• Not to mention the visual validation you can do with a diagram! ;)
  (mermaid is supported and can be added in the doc)
• Maybe I'd take the opportunity to clarify how to define custom passwords. fab.yaml instructs you to:
  password hash use openssl passwd -5`

[mrbojangles3]

If we are okay with referring to line numbers I am good with switching to them. There is also the option to have the line numbers start at a given number. So we could have a big listing then break it up in sections to talk about it. Thoughts @pau-hedgehog and @qmonnet

[qmonnet]

If we are okay with referring to line numbers I am good with switching to them

I don't know. Is there a way to reference a specific line an turns that ref into a number under the YAML sample, or do you manually reference the line number, and risks the line number getting outdated if someone inserts more lines into the YAML snippet in the future?

[mrbojangles3]

It would be a pretty manual process. We would take the example file and have to manual start the line numbers ourselves. Very easy to get out of sync.

[qmonnet]

I'm still in favour of the footnote (or inline comment) in that case 😅.

[mrbojangles3]

What do you think of the look on the material for mkdocs webpage - https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations. It doesn't seem like we are getting the same functionality that is shown on the page.

[qmonnet]

Ooooh so that's what you were trying to do! That's cool, now we just need to understand how to make it work 🙂

[qmonnet]

Try adding a blank line between the YAML snippet and the annotation, just in case?

[pau-hedgehog]

What do you think of the look on the material for mkdocs webpage - https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations. It doesn't seem like we are getting the same functionality that is shown on the page.

We may be missing this: https://github.com/pawamoy/mkdocs-pygments ?

[mrbojangles3]

It was the blank line. Had to step away will update when back. Logan Blyth

…

On Fri, Mar 21, 2025 at 11:31 AM Pau Capdevila ***@***.***> wrote: What do you think of the look on the material for mkdocs webpage - https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations. It doesn't seem like we are getting the same functionality that is shown on the page. image.png (view on web) <https://github.com/user-attachments/assets/d5dc71e4-57a7-4af1-b814-caadd38ff0cf> We may be missing this: https://github.com/pawamoy/mkdocs-pygments ? — Reply to this email directly, view it on GitHub <#77 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABXI6A54RWTWYNYFQJG5JL2VQWGDAVCNFSM6AAAAABZL3QKUOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBTG4ZTCMRSGU> . You are receiving this because you authored the thread.Message ID: ***@***.***> [image: pau-hedgehog]*pau-hedgehog* left a comment (githedgehog/docs#77) <#77 (comment)> What do you think of the look on the material for mkdocs webpage - https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations. It doesn't seem like we are getting the same functionality that is shown on the page. image.png (view on web) <https://github.com/user-attachments/assets/d5dc71e4-57a7-4af1-b814-caadd38ff0cf> We may be missing this: https://github.com/pawamoy/mkdocs-pygments ? — Reply to this email directly, view it on GitHub <#77 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABXI6A54RWTWYNYFQJG5JL2VQWGDAVCNFSM6AAAAABZL3QKUOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBTG4ZTCMRSGU> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[mrbojangles3]

Force pushed into a single commit. Kept the help provided by the team in the message. I hope that means y'all still get the credit.

[qmonnet]

Looks good, thank you!
Some additional ramblings below, but not blocking for this PR.

I hope that means y'all still get the credit.

Thanks! Although I don't mind much being mentioned for small suggestions like these, it's more review feedback than actual contributions to the docs contents.

When you squash, though, try keeping all the tags at the end of the commit description (and don't hesitate to reword the description). Assuming I really wanted to credit reviewers for the suggestions, I'd so something like:

install-upgrade: Add example wiring diagram

Provide a sample, annotated wiring diagram to help users create
theirs. Also add line numbering to several YAML snippets, to
make it easier to reference specific lines.

[ Pau: Fixed a typo ]
[ Quentin: Suggested improvements on YAML annotations ]

Signed-off-by: Logan Blyth <logan@githedgehog.com>
Co-authored-by: Quentin Monnet <qmo@qmon.net>
Signed-off-by: Quentin Monnet <qmo@qmon.net>
Signed-off-by: Pau Capdevila <pau@githedgehog.com>

The kernel has strict rules according to which all Co-authored-by: tags (or the kernel equivalents) must come along a Signed-off-by:, but it's probably more than we care for.

[Frostman]

@qmonnet do you want to have another look and merge as you were reviewing it before?

[qmonnet]

Thanks! All good from my side

[qmonnet]

Except that I can't bypass the new workflow 🙂

[qmonnet]

My bad - it was just a matter of marking the comments as “resolved”.

@mrbojangles3 would you mind rebasing on top of master to get rid of that merge commit, please?