[FEATURE] Documentation Improvements

[God-damnit-all]

[FEATURE] Documentation Improvements

[God-damnit-all]

@wez Unless I'm mistaken, it looks like this is more or less complete or at least getting close to it, ya? So this probably doesn't need to be open anymore.

[wez]

Docs are always hard to maintain. I'll give this some thought!

• Dark Mode: It's like staring at the sun.
  • Add a button to toggle a dark theme, like a light bulb.
  • Just make it dark for everyone because who the hell doesn't use dark mode?

Heh, yeah, I'm a a dark mode fan also!

[wez]

Here's my current line of thinking on this:

The nightly (which is actually hourly!) build is to make it easier for folks to try the bleeding edge without needing to set up a compilation environment. It is explicitly considered to be unstable and as such may not work at all and may be half-baked. It's hard to justify stringent documentation requirements for something of that nature.

I generally aim to add docs for new things in the commit messages as the associated features come together, and then when I'm ready to release I'll collect notes into the release (see https://github.com/wez/wezterm/releases) and write up the docs for the website. I think that is a reasonable model, but there is an obvious gap in that the release notes aren't visible on the website that should be addressed.

For configuration options: in earlier versions the config was a few tens of lines of code (mostly comments) that could be linked directly, but as the project has grown it's gotten a bit more complex.
It is technically possible to automatically extract the doc comments from the code, but it is a project in itself to make automatically extracted documentation be actually useful and good.

Another facet of this is that the current TOML config is "OK" but it's not going to work for some the features that I have in mind so I've been working an alternative. I'd rather get that to a good place before investing energy into automation around documentation.

[God-damnit-all]

I had a bit of an odd idea for the configuration. The way Python code formatting works is a lot like YAML. What if wezterm used the embeddable version of Python and compiled it into the wezterm binary (to keep it as a single executable).

Python isn't known for performance, but it's not like you need high performance for this use-case. Any given option could potentially handle both three-state-booleans and strings.

[God-damnit-all]

Also, thanks for reducing the size of the pdb. 👍

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues. If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.