overhaul ConfigManager, add basic tests, add basic docs
This commit is contained in:
238
README.md
238
README.md
@@ -1,233 +1,11 @@
|
||||
# autoconf
|
||||
The `autoconf` project is an attempt at wrangling the complexity of configuring many
|
||||
applications across one's Linux system. It provides a simple operational model for pulling
|
||||
many application config files into one place, as well as generating/setting color schemes
|
||||
across apps.
|
||||
# Overview
|
||||
`symconf` is a CLI tool for managing local application configuration. It uses a simple
|
||||
operational model that symlinks centralized config files to their expected locations across
|
||||
the system. This central config directory can then be version controlled.
|
||||
|
||||
Quick terminology rundown for theme-related items:
|
||||
`symconf` also facilitates dynamically setting system and application "themes," symlinking
|
||||
matching theme config files for registered apps and running config reloading scripts.
|
||||
|
||||
- **Theme**: loose term referring generally to the overall aesthetic of a visual setting.
|
||||
Ignoring stylistic changes (only applicable to some apps; example here might be a
|
||||
a particular setting of the `waybar` layout), a theme is often just the wrapper term for
|
||||
a choice of color _palette_ and _scheme_. For example, "tone4-light" could be a _theme_
|
||||
setting for an app like `kitty`, referring to both a palette and scheme.
|
||||
- **Palette**: a set of base colors used to style text or other aspects of an app's
|
||||
displayed assets
|
||||
- **Scheme**: an indication of lightness, typically either "light" or "dark.
|
||||
For
|
||||
example, the following `symconf` call coordinates a light to dark mode switch
|
||||
|
||||
As far as managing settings across apps, there are current two useful classifications
|
||||
here:
|
||||
|
||||
1. **Inseparable from theme**: some apps (e.g., `sway`, `waybar`) have color scheme
|
||||
components effectively built in to their canonical configuration file. This can make it
|
||||
hard to set themes dynamically, as it would likely require some involved
|
||||
matching/substitution rules. This is not a level of complexity I'm willing to embrace,
|
||||
so we simply split the config files according to theme and/or scheme.
|
||||
2. **Can load an external theme file**: some apps (e.g., `kitty`) have a clear mechanism
|
||||
for loading themes. This typically implies some distinct color format, although usually
|
||||
somewhat easy to generate (don't have to navigate non-color settings, for instance).
|
||||
Such apps allow for an even less "invasive" config swapping process when setting a new
|
||||
theme, as one can just swap out the external theme file.
|
||||
|
||||
To be clear on operation implications here: apps of type (1) must have _manually
|
||||
maintained_ config variations according the desired themes. General theme settings must
|
||||
follow the naming scheme `<app-name>-<palette>-<scheme>.<ext>`. For example, if I wanted to set
|
||||
`sway` to a light variation (which, at the time of writing, would just entail changing a
|
||||
single background color), I must have explicitly created a `sway-tone4-light.conf` file
|
||||
that captures this setting. The canonical config file will then be symlinked to the
|
||||
theme-specific file when the theme is set. (Note that the palette in this example is pretty much
|
||||
irrelevant, but it needs to be present in order to match the overarching setting; here you
|
||||
can just think of the format being `<app-name>-<theme>.<ext>`, where `tone4-light` is the
|
||||
provided theme name.)
|
||||
|
||||
For apps of type (2), the canonical config file can remain untouched so long as it refers
|
||||
to a fixed, generic theme file. For example, with `kitty`, my config file can point to a
|
||||
`current-theme.conf` file, which will be symlinked to a specific theme file here in
|
||||
`autoconf` when a change is requested. This enables a couple of conveniences:
|
||||
|
||||
- The true config directory on disk remains unpolluted with theme variants.
|
||||
- If the set theme is regenerated, there is no intervention necessary to propagate its
|
||||
changes to the target app. The symlinked file itself will be updated when the theme
|
||||
does, ensuring the latest theme version is always immediately available and pointed to
|
||||
by the app.
|
||||
|
||||
Keep in mind that some apps may fall into some grey area here, allowing some external
|
||||
customization but locking down other settings internally. In such instances, there's no
|
||||
need to overcomplicate things; just stick to explicit config variants under the type (1)
|
||||
umbrella. Type (2) only works for generated themes anyhow; even if the target app can load
|
||||
an external theme, type (1) should be used if preset themes are fixed.
|
||||
|
||||
## Naming standards
|
||||
To keep things simple, we use a few fixed naming standards for setting app config files
|
||||
and their themed counterparts. The app registry requires each theme-eligible app to
|
||||
provide a config directory (`config_dir`), containing some canonical config file
|
||||
(`config_file`) and to serve as a place for theme-specific config variations. The
|
||||
following naming schemes must be used in order for theme switching to behave
|
||||
appropriately:
|
||||
|
||||
- When setting a theme for a particular app, the following variables will be available:
|
||||
* `<app-name>`
|
||||
* `<palette>`
|
||||
* `<scheme>`
|
||||
- For apps with `external_theme = False`, config variants must named as
|
||||
`<app-name>-<palette>-<scheme>.<ext>`, where `<ext>` is the app's default config file
|
||||
extension.
|
||||
- For apps with `external_theme = True`, the file `<config-dir>/current-theme.conf` will
|
||||
be used when symlinking the requested theme. The config file thus must point to this
|
||||
file in order to change with the set theme.
|
||||
|
||||
Additionally, the theme symlink will be created from the file
|
||||
|
||||
```
|
||||
<autoconf-root>/autoconf/themes/<palette>/apps/<app-name>/generated/<scheme>.conf
|
||||
```
|
||||
|
||||
to `<config-dir>/current-theme.conf`.
|
||||
|
||||
## Directory structure
|
||||
|
||||
- `autoconf/`: main repo directory
|
||||
* `config/`: app-specific configuration files. Each folder inside this directory is
|
||||
app-specific, and the target of associated copy operations when a config sync is
|
||||
performed. Nothing in this directory should pertain to any repo functionality; it
|
||||
should only contain config files that originated elsewhere on the system.
|
||||
* `themes/`: app-independent theme data files. Each folder in this directory should
|
||||
correspond to a specific color palette and house any relevant color spec files
|
||||
(currently likely be a `colors.json`). Also servers the output location for
|
||||
generated theme files
|
||||
* `<palette>/colors.json`: JSON formatted color key-value pairings for palette
|
||||
colors. There's no standard here aside from the filename and format; downstream
|
||||
app-specific TOML templates can be dependent on any key naming scheme within the
|
||||
JSON.
|
||||
+ `<palette>/apps/<app-name>/templates/`: houses the TOML maps for the color
|
||||
palette `<palette>` under app `<app-name>`. Files `<fname>.toml` will be mapped to
|
||||
`<fname>.conf` in the theme output folder (below), so ensure the naming
|
||||
standards align with those outlined above.
|
||||
+ `<palette>/apps/<app-name>/generated/`: output directory for generated scheme
|
||||
variants. These are the symlink targets for dynamically set external themes.
|
||||
* `app_registry.toml`: global application "registry" used by sync and theme-setting
|
||||
scripts. This lets apps be dynamically added or removed from being eligible for
|
||||
config-related operations.
|
||||
|
||||
## Scripts
|
||||
|
||||
`set_theme.py`: sets a theme across select apps.
|
||||
|
||||
- Applies to specific app with `-a <app>` , or to all apps in the `app_registry.toml` with
|
||||
`-a "*"`.
|
||||
- Uses symlinks to set canonical config files to theme-based variations. Which files get
|
||||
set depends on the _app type_ (see above), which really just boils down to whether
|
||||
theming (1) can be specified with an external format, and (2) if it depends on
|
||||
auto-generated theme files from within `autoconf`.
|
||||
- Palette and scheme are specified as expected. They are used to infer proper paths
|
||||
according to naming and structure standards.
|
||||
- Real config files will never be overwritten. To begin setting themes with the script,
|
||||
you must delete the canonical config file expected by the app (and specified in the app
|
||||
registry) to allow the first symlink to be set. From there on out, symlinks will be
|
||||
automatically flushed.
|
||||
- A report will be provided on which apps were successfully set to the requested theme,
|
||||
along with the file stems. A number of checks are in place for the existence of involved
|
||||
files and directories. Overall, the risk of overwritting a real config file is low; we
|
||||
only flush existing symlinks, and if the would-be target for the requested theme (be it
|
||||
from an auto-generated theme file, or from a manually manage config variant) doesn't
|
||||
exist, that app's config will be completed skipped. Essentially, everything must be in
|
||||
perfect shape before the symlink trigger is officially pulled.
|
||||
|
||||
|
||||
`gen_theme.py`: generates theme files for palettes by mapping their color definitions
|
||||
through app-specific templates. These templates specific how to relate an app's theme
|
||||
variables to the color names provided by the template.
|
||||
|
||||
- An app and palette are the two required parameters. If no template or output paths are
|
||||
provided, they will be inferred according to the theme path standards seen above.
|
||||
- The `--template` argument can be a directory or a file, depending on what theme files
|
||||
you'd like to render.
|
||||
- The `--output` path, if specified, must be a directory. Generated theme files take on
|
||||
a name with the same stem as their source template, but using the `.conf` extension.
|
||||
- The TOML templates should make config variable names to JSON dot-notation accessors. If
|
||||
color definitions are nested, the dot notation should be properly expanded by the script
|
||||
when mapping the colors to keyword values.
|
||||
- There are a number of checks for existing paths, even those inferred (e.g., template and
|
||||
output) from the palette and app. If the appropriate setup hasn't been followed, the
|
||||
script will fail. Make sure the `theme` folder in question and it's nested `app`
|
||||
directory are correctly setup before running the script. (Perhaps down the line there
|
||||
are some easy auto-setup steps to take here, but I'm not making that jump now.)
|
||||
- TODO: open up different app "writers," or make it easy to extend output syntax based on
|
||||
the app in question. This would like be as simple as mapping app names to
|
||||
line-generating functions, which accept the keyword and color (among other items). This
|
||||
can be fleshed out as needed.
|
||||
|
||||
`sync.sh`: copies relevant configuration files from local paths into the `autoconf`
|
||||
subpath. Markdown files in the docs directory then reference the local copies of these
|
||||
files, meaning the documentation updates dynamically when the configuration files do. That
|
||||
is, the (possibly extracted) config snippets will change with the current state of my
|
||||
system config without any manual intervention of the documentation files.
|
||||
|
||||
### Specific theme-setting example
|
||||
To make clear how the theme setting script works on my system, the following breaks down
|
||||
exactly what steps are taken to exert as much scheme control as possible. Everything at this
|
||||
point is wrapped up in a single `make set-<palette>-<scheme>` call; suppose we're
|
||||
currently running the dark scheme (see first image) and I run `make set-tone4-light`:
|
||||
|
||||
|
||||
|
||||
_(Starting point; have a GTK app (GNOME files), `kitty`, and Firefox (with the
|
||||
system-dependent default theme set). In Firefox, I have open `localsys` with its
|
||||
scheme-mode to set to "auto," which should reflect the theme setting picked up by the
|
||||
browser (and note the white tab icon).)_
|
||||
|
||||
1. `set_theme.py` is invoked. Global settings are applied first, based on my OS (`Linux`),
|
||||
which calls
|
||||
|
||||
```
|
||||
gsettings set org.gnome.desktop.interface color-scheme 'prefer-light'
|
||||
```
|
||||
|
||||
controlling settings for GTK apps and other `desktop-portal`-aware programs. This
|
||||
yields the following:
|
||||
|
||||
|
||||
|
||||
_(Portal-aware apps changed, config apps not yet set. Scheme-aware sites are updated
|
||||
without page refresh.)_
|
||||
2. Specific application styles are set. For now the list is small, including `kitty`,
|
||||
`waybar`, and `sway`. `kitty` is the only type (2) application here, whereas the other
|
||||
two are type (1).
|
||||
|
||||
a. For the type (1) apps, the canonical config files as specified in the app registry
|
||||
are symlinked to their light variants. For `sway`, this is `~/.config/sway/config`,
|
||||
and if we look at the `file`:
|
||||
|
||||
```sh
|
||||
.config/sway/config: symbolic link to ~/.config/sway/sway-tone4-light
|
||||
```
|
||||
b. For the type (2) apps, just the `current-theme.conf` file is symlinked to the
|
||||
relevant palette-scheme file. `kitty` is such an app, with a supported theme file
|
||||
for `tone4`, and those files have been auto-generated via `gen_theme.py`. Looking at
|
||||
this file under the `kitty` config directory:
|
||||
|
||||
```sh
|
||||
.config/kitty/current-theme.conf: symbolic link to ~/Documents/projects/autoconf/autoconf/themes/tone4/apps/kitty/generated/light.conf
|
||||
```
|
||||
|
||||
The `kitty.conf` file isn't changed, as all palette-related items are specified in
|
||||
the theme file. (Note that the general notion of a "theme" could include changes to
|
||||
other stylistic aspects, like the font family; this would likely require some hybrid
|
||||
type 1-2 approach not yet implemented).
|
||||
3. Live application instances are reloaded, according to the registered `refresh_cmd`s.
|
||||
Here the apps with style/config files set in step (2) are reloaded to reflect those
|
||||
changes. Again, in this example, this is `kitty`, `sway`, and the `waybar`.
|
||||
|
||||
|
||||
|
||||
_(Final light setting: portal-dependent apps _and_ config-based apps changed)_
|
||||
4. `set_theme.py` provides a report for the actions taken; in this case, the following was
|
||||
printed:
|
||||
|
||||
|
||||
_(`set_theme.py` output)_
|
||||
|
||||
Reference in New Issue
Block a user