docs: Add documentation for config options

[joelspadin]

This adds a new "config" section to the sidebar with documentation on (most of) the Kconfig and Devicetree options we support.

I documented everything manually, because I didn't want to try to figure out how to write a Kconfig parser in JavaScript, get it reading files from outside the docs directory, and organize it in a reasonable way. As a future improvement, we could try to generate some of this dynamically so it can't get out of sync with the code.

This also adds a section describing how to actually edit configuration, and I replaced some redundant information in the rest of the documentation with links to the new pages.

[caksoylar]

I don't think this link is relevant to grave-escape, though I couldn't find any existing docs that would describe it.

[joelspadin]

Thanks. It looks like I pasted the wrong thing in there. There doesn't appear to be any existing documentation for grave escape.

[caksoylar]

I think this is great: It formally documents things that I had to search in other places like deep sleep config and things I had to look up external resources to learn more about, like devicetree syntax details.

[joelspadin]

Reworded the description of timeout-ms on the combos feature and config pages to make it clearer what it does.

[joelspadin]

This fixes #628 and #717

[okke-formsma]

Maybe we should merge the behavior & combo pages with the existing behavior docs. I think I'd rather have a few longer pages than splitting the documentation for a single thing up into multiple parts.

[joelspadin]

Maybe we should merge the behavior & combo pages with the existing behavior docs. I think I'd rather have a few longer pages than splitting the documentation for a single thing up into multiple parts.

On one hand, that does avoid splitting the documentation for combos and behaviors into multiple parts. On the other, it's not very consistent with the pages that aren't combos and behaviors.

I went with this because https://discord.com/channels/719497620560543766/719544230497878116/814229818635452436

petejohanson (US ET)02/24/2021
I think a unified config section, with links to features as appropriate, makes sense to me.

[petejohanson]

Yeah, there's definitely pros/cons here. I'm certainly open to suggestions.

My thinking at the time was that "configuration" spans more than just behaviors, including deep sleep settings, logging, enabling displays, etc.

That being said, we theoretically cover "all of those things" if you combine both the "Features" and "Behaviors" sections of our docs.

I suppose the question then becomes:

Do we document the general feature/behavior, and everything to configure it in one spot?

We already do this somewhat with the behavior docs, and some of the features, e.g. encoders.

Pros to a dedicated "configuration section"

• One spot to find everything about configuring/changing ZMK
• Spans behaviors, and non-behavior configuration.

Pros to "config lives w/ main description"

• No arbitrary division of description/usage and configuration.
• No need to keep two pieces in sync.

@Nicell @innovaker Any opinion?

[Nicell]

I like the idea of having behaviors and configs combined under one feature page, but it's true that some of our features aren't quite that simple that you can easily do that, and some configs or behaviors don't really have a feature underneath them.

We could have things split up (features, behaviors, configs pages) and use MDX to have the configs copied under the associated feature/behavior and have the behaviors copied under the associated feature. That was we could have everything split up as we please with easier management and linking without being confined to features necessarily, but we also get the benefit of all relevant information being on each feature/behavior page.

This would result in duplicate information across the pages though. Curious what people think of this.

[caksoylar]

What do the contributors think about the current status of this PR? I see the discussion about not splitting config into a dedicated section like this, but I'd still see merit in merging this if there isn't a large objection. Can it be potentially refactored later on if it is decided that the merged docs are better?

I think there is a lot of valuable information here regarding how configuration works in general and previously undocumented settings for displays and enabling deep sleep. We sometimes end up referring users to the Netlify preview of this PR and that is not great.

[Charghoul]

I really like it, some documentation is always better then none and this is a good and thorough starting point.

[dxmh]

There's a lot of really great ideas in this thread with regards to reorganising the content and/or generating it dynamically. But to move this PR forwards, I agree with the comments above that these things can come later.

There is an incredible amount of valuable information here that users are often seeking – links to pages in the Netlify preview for this PR are shared quite regularly. It would be great to have this resource live in the official docs.

If we can get this rebased and ensure the content is still accurate, I recommend we merge this. 🙂

[joelspadin]

Rebased and updated with all the new features and changes to existing ones I could find since I originally wrote this.

[dxmh]

Awesome, thanks for bringing this up to date @joelspadin!

I haven't yet had the chance to review this, but I noticed that your latest push is now causing some of the checks to fail: https://github.com/zmkfirmware/zmk/runs/6237433731?check_suite_focus=true

I also spotted a small issue with the links which I've mentioned below.

[dxmh]

As of #1330, the default continue-list is now as follows:

Suggested change

	| `continue-list` | array | List of [key codes](/docs/codes) which do not deactivate caps lock | `<UNDERSCORE>` |
	| `continue-list` | array | List of [key codes](/docs/codes) which do not deactivate caps lock | `<UNDERSCORE BACKSPACE DELETE>` |

[dxmh]

@joelspadin If you're able to incorporate the few minor suggestions above, then I think we'd be good to merge!

[caksoylar]

This would be great to merge before we add even more config options; we still keep referring folks to the preview docs for various issues.

[dxmh]

@caksoylar What do you think about merging as-is, without incorporating the suggestions above? These minor things could then be addressed in a separate follow-up PR?

[caksoylar]

@dxmh That's a good idea, I can open a follow up PR for my suggestions.

[dxmh]

Let's merge. 🙂

Thank you @joelspadin for all the effort you put into this awesome documentation! 👍