[FEATURE] Documentation Improvements

[God-damnit-all]

It seems that the site is using some sort of ruby-based system to manage the website with markdown files, I can see how it works but I'm not familiar with its full feature set, so I'll put different ways of accomplishing my suggestions in sub-points.

• Nightly differences: Not only is this good from an end-user point of view, but it should also be good to have this all in one place for when the next stable is ready.
  • Move the nightly download to a different page and list the differences alongside it.
  • Maintain a stable and nightly version of the site. When a new stable is ready, overwrite the stable docs with the nightly docs.
  • Use some sort of diff system to generate a nightly version of the site dynamically.
• 'Smart' documentation: Be it directly or indirectly, the documentation should be linked to the build process, particularly for configuration docs.
  • Generate a warning in the build process when the nightly docs references something that no longer exists
  • Generate documentation from the code directly by putting strings in the functions that need to be documented and doing something clever with github-actions
  • Unfortunately I don't know how projects normally do this so there's probably something way more obvious I haven't thought of.
• 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?

[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]

@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.

[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.