I feel like recommending people install Poetry via a package manager was
a mistake. Poetry only supports its latest version, and while newer
versions are sort-of backward-compatible, they print warnings in
different situations and have different bugs. Installing `pipx` via a
package manager, OTOH, works fine, and its older versions work fine.
Using Poetry 1.8+ allows us to use Poetry's new "non-package" mode,
which would no longer print warnings if the user does `poetry install`
instead of `poetry install --no-root`. It's likely that in newer
versions of Poetry, it will become an error.
https://github.com/squidfunk/mkdocs-material/issues/7160 is supposed to
be fixed now. I will double-check that the version switcher still works
after this commit. This only affects the version switcher from
"prerelease" to other versions.. The functionality is a bit brittle, so
it's hard to test locally before merging this.
We do want to upgrade, since this allows us (and seems to also require
us) to upgrade to MkDocs 1.6, which has a nice feature of disallowing
links to broken document section (beyond just checking for links to
non-existent files).
I carefully avoided unnecessary upgrades in this commit, but we
should also run `poetry update` shortly, once we check this
works properly. Also, the feature of MkDocs 1.6 I mentioned needs
enabling.
Finally, I plan to change version specifiers from Poetry's `^5.6.22`
syntax to more plain inequalities, since I keep forgetting what the
former syntax means. I started with this commit.
(I was surprised MkDocs was allowed to be upgraded to `1.6` with the
`^1.5.2` spec. I now suspect that what I previously thought it should
mean is expressed as `~1.5.2`, but inequalities are clearer).
https://github.com/jimporter/mike/releases/tag/v2.0.0
The main immediate advantage of this is that `mike` will stop pushing empty
commits.
Also, we can consider switching to using symlinks instead of redirects for
mapping the "latest" version to "v0.11.0". This would make
`https://martinvonz.github.io/jj/latest/` have the same content as
`https://martinvonz.github.io/jj/v0.11.0/` (until the next version is out), but
the user would see `latest` in the URL.
For now, I set an option to keep using redirects.
I did a bit of non-exhaustive testing; it seems to work.
This adds two MkDocs extensions to make list handling more flexible.
It took some trial-and-error, but it seems this config works OK.
revsets.md: use saner formatting that is now possible.
sapling-comparison.md: this was the one case I saw made worse by the
new plugins. I changed the Markdown formatting, it still looks sane.
I initially was thinking of using `mdbook`, which looks a little better, but I
think versioning the docs is important, and the features I want are pretty much
only supported by the Mkdocs' "Material" theme.
Mkdocs is written in Python. The prerequesites for building docs on your
machine should be to install Python and Poetry, everything else should be
installed automatically by Poetry. See the edits to `contributing.md` for more details.
