This commit adds some plumbing to allow us to collect metadata
about the caches and spit it out into a json file that we can
then use in the docs to show the predefined caches, capacities
and brief comments about their purpose.
We put that info on the set_lruttl_cache_capacity doc page.
This macro allows embedding TOML data into the docs,
and showing it in a tab that has both the TOML and JSON
representation of that data.
It works by executing the toml2jsonc helper that was added
in an earlier commit.
There's some machinery here to compile that utility to run
in the context of the mkdocs docker image; that works
locally, let's see how well it works in CI!
Usage is simple; before:
```toml
["something"]
foo = "bar"
```
after:
{% call toml_data() %}
["something"]
foo = "bar"
{% endcall %}
The first page to get switched over to this is https://docs.kumomta.com/tutorial/configuring_kumomta/
refs: https://github.com/KumoCorp/kumomta/issues/212
It's a PITA to bootstrap the docker daemon, and pointing it to the host
daemon to sidestep all that is insecure and should not be trusted in a
public repo like this.
So, let's just try podman for this: it doesn't need a daemon and
doesn't need any special privs.
I definitely forgot to do this on the very first change after
adding them, so I want to make it less likely in the future.
This causes the specs to get updated in the docs if they have
changed (other than the version field) since the last time they
were updated.
We check this during test and doc building. That should be
sufficient to catch this during my dev loop.
refs: https://github.com/KumoCorp/kumomta/issues/96
Ideally there would be a good mkdocs based checker, but the
one that is out there only validate absolute URLs, which makes
it unsuitable for checking local relative links in the docs.
Adjust the doc build so that we also generate the SUMMARY.md
for mdbook, and use mdbook's link checker to check the links.
Fixup the couple of broken links that it found.
Previously, I was cleaning up some junk like _index directories
generated from the _index.md fragments. I noticed that those
were showing up in the search index, so it is better to exclude
from the outset. mkdocs doesn't natively support the idea of
exclusion, but there is a plugin that does, so use it.
I'd carried over behavior from wezterm where we only considered
tracked markdown files, which could be confusing for newly
authored files: they wouldn't get considered or updated until
they had been committed.
the pages workflow silently corrects these so they go unnoticed,
leaving the corrections to show up for the next person to run
`docs/build.sh`, polluting their later commit with unrelated
changes.
Augment the verify-pages workflow to also run on `main` and
surface the corrections with a failed workflow run.
Wez Furlong
drone