Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Physical layout docs improvements #2533

Merged
merged 23 commits into from
Oct 12, 2024

Conversation

Nick-Munnich
Copy link
Contributor

@Nick-Munnich Nick-Munnich commented Oct 3, 2024

Tried to do a revamp for improved clarity and to match the refactoring plan from #2515.

  • Added a new configuration page called layout
    • Added physical layout reference information
    • Added position map reference information
    • Moved matrix transform reference information and updated the description somewhat
  • Changed studio setup section to physical layout section
    • Moved information out of new shield into said section
    • Reworked the position map stuff to (imo) be more clear
  • Added a note in new shield that &studio_unlock should be added to the reference keymap if the device is intended for use with zmk studio

There is some duplicated information between physical layout section and the config section. I think it's fine to have it duplicated, but would also be fine with removing one of the copies.

Subsumes #2527

@Nick-Munnich Nick-Munnich requested a review from a team as a code owner October 3, 2024 22:29
@Nick-Munnich Nick-Munnich added the documentation Improvements or additions to documentation label Oct 3, 2024
@Nick-Munnich Nick-Munnich added the studio ZMK Studio (runtime keymaps) label Oct 3, 2024
Copy link
Contributor

@petejohanson petejohanson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the work on this! In general, I think this is a major imporvement, just a few thoughts on the layout bits vis-a-vis studio's alpha-almost-beta status.

docs/docs/config/layout.md Show resolved Hide resolved
Copy link
Contributor

@caksoylar caksoylar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like I mentioned offline, I'll also look into replacing the PNG with an SVG -- that should hopefully work well with both light/dark themes.

@caksoylar
Copy link
Contributor

Another note, it might be nice to have a pointer to the physical layouts page in the ZMK Studio feature page, similar to https://zmk.dev/docs/features/encoders#adding-encoder-support

Copy link
Contributor Author

@Nick-Munnich Nick-Munnich left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One thing I didn't note in a comment but I also changed is the addition of labels to position map child nodes, following this comment and conversation on Discord.

Copy link
Contributor

@petejohanson petejohanson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Look good, generally. One minor comment/question.

Copy link
Contributor

@caksoylar caksoylar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mostly small comments, I think the new explanations certainly help.

@Nick-Munnich
Copy link
Contributor Author

Added a note on putting physical layouts into keyboard-layouts.dtsi. Also changed the TOC depth so that the examples show up in it.

@petejohanson
Copy link
Contributor

@Nick-Munnich Can you please mark as resolved any of the items you've addressed, so we can see what (if anything) is still outstanding here from the review comments?)

@Nick-Munnich
Copy link
Contributor Author

All the comments have been addressed, just wanted to let it stew for a bit in case of any further comments. Should be good to merge tonight if no other comments appear.

Copy link
Contributor

@petejohanson petejohanson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. @caksoylar any concerns?

@caksoylar
Copy link
Contributor

I am good, I wanted to give @joelspadin a day or so in case he has comments.

docs/static/_redirects Outdated Show resolved Hide resolved
@Nick-Munnich Nick-Munnich merged commit a72327b into zmkfirmware:main Oct 12, 2024
7 checks passed
@Nick-Munnich Nick-Munnich deleted the studio-doc-improvements branch October 12, 2024 19:25
lammai pushed a commit to lammai/zmk that referenced this pull request Oct 27, 2024
* docs: Added layout configuration reference page
* docs: Refactored and revamped physical layout creation information
* docs: Added note in studio features page
* docs: added studio_unlock note in features section
---------

Co-authored-by: Cem Aksoylar <[email protected]>
Co-authored-by: Joel Spadin <[email protected]>
Co-authored-by: Peter Johanson <[email protected]>
EnotionZ pushed a commit to EnotionZ/zmk that referenced this pull request Nov 6, 2024
* docs: Added layout configuration reference page
* docs: Refactored and revamped physical layout creation information
* docs: Added note in studio features page
* docs: added studio_unlock note in features section
---------

Co-authored-by: Cem Aksoylar <[email protected]>
Co-authored-by: Joel Spadin <[email protected]>
Co-authored-by: Peter Johanson <[email protected]>
earwin pushed a commit to earwin/zmk that referenced this pull request Nov 13, 2024
* docs: Added layout configuration reference page
* docs: Refactored and revamped physical layout creation information
* docs: Added note in studio features page
* docs: added studio_unlock note in features section
---------

Co-authored-by: Cem Aksoylar <[email protected]>
Co-authored-by: Joel Spadin <[email protected]>
Co-authored-by: Peter Johanson <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation studio ZMK Studio (runtime keymaps)
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants