Commit graph

15 commits

Author SHA1 Message Date
Emily
cedaa5bb00 docs: migrate from poetry to uv
Our docs are built with MkDocs, which requires Python and several deps.

Previously those deps were managed with Poetry, which is also written in Python.
This commit replaces Poetry with `uv`, a Rust-based Python
project/package manager, and thus removes several steps from the docs
build process.

Before:

  <install Python>
  <install pipx>
  pipx install poetry
  poetry install
  poetry run -- mkdocs serve

After:

  <install uv>
  uv run mkdocs serve
2024-11-20 06:06:53 +01:00
Ilya Grigoriev
d34198d111 docs: update mkdocs-material with bugfix, poetry update
This will hopefully make the version switcher stay
on the same page as it includes
https://github.com/squidfunk/mkdocs-material/pull/7559.
Unfortunately, it might break again for reasons explained
there.
2024-09-29 13:56:08 -07:00
Ilya Grigoriev
92403d7d11 require poetry 1.8, recommend installing it via pipx
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.
2024-05-27 10:53:35 -07:00
Ilya Grigoriev
54e04e4ac3 update mkdocs-material & poetry update
The new version supports showing labels in version selector.
2024-05-21 16:19:04 -07:00
Ilya Grigoriev
4907a384b9 docs: update dependency versions, poetry update 2024-05-14 13:14:27 -07:00
Ilya Grigoriev
02b72e542d docs: try upgrading mkdocs-material again, upgrade MkDocs
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).
2024-05-13 09:14:33 -07:00
Ilya Grigoriev
60ee462369 docs: downgrade mkdocs-material
I'm hoping this will fix version switching.

https://github.com/squidfunk/mkdocs-material/issues/7160
2024-05-07 09:03:21 -07:00
Ilya Grigoriev
b170988a46 poetry: add the include-markdown MkDocs plugin 2024-02-12 10:28:09 -08:00
Ilya Grigoriev
54a967a1b3 docs: update mkdocs-material to 9.5
This will allow for better toggles in
https://github.com/martinvonz/jj/pull/2783
2024-01-07 12:45:45 -08:00
Ilya Grigoriev
ed245e234d poetry: Update pyproject.toml to use newer convention
The previous commit checks that Poetry down to version 1.3.2 (current Debian
stable version) support it.
2023-11-06 17:10:27 -08:00
Ilya Grigoriev
5fc649cbee website: upgrade mike to version 2.0
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.
2023-11-04 12:23:16 -07:00
Ilya Grigoriev
e701b08f42 poetry: update mkdocs-material in pyproject.toml
Considering the previous commit, it's unclear how compatible we are
with previous mkdocs-material versions.
2023-11-03 19:15:37 -07:00
Ilya Grigoriev
adc8433204 mkdocs: make MkDocs work with more GitHub-like list formatting
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.
2023-11-03 19:15:37 -07:00
Ilya Grigoriev
2218143968 docs: create a basic homepage for the docs website
Before, https://martinvonz.github.io/jj/latest redirected to
https://martinvonz.github.io/jj/latest/install-and-setup.html.

Now, it will direct people to a basic page with a link to
the repo and a few other useful pages.

An additional motivation is the desire to have a homepage to
link to from
https://github.com/martinvonz/jj/pull/2273#discussion_r1331008117.

Better something very basic than nothing.
2023-10-03 19:58:22 -07:00
Ilya Grigoriev
fc49258d2f docs: Set up mkdocs and poetry
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.
2023-08-28 10:43:48 -07:00