jj/pyproject.toml

# The `dev-dependencies` section sets up tools for building `jj`
# documentation. `poetry` will install these in a virtual environment.
[tool.poetry]
name = "jj-docs"
package-mode = false

[tool.poetry.dependencies]
python = "^3.8"

[tool.poetry.group.dev.dependencies]
# These can be updated with `poetry add`.
mkdocs = ">=1.6,<1.7"
mkdocs-material = ">=9.5.24,<9.6"
# Versioning of documentation
mike = ">=2.1.1,<3"
# (Py)Markdown extensions
mdx-truly-sane-lists = "^1.3"
mdx-breakless-lists = "^1.0.1"
# Allows setting up redirects when renaming docs files
mkdocs-redirects = "^1.2.1"
# Used for the CLI reference
mkdocs-include-markdown-plugin = "^6.0.4"
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-18 23:43:20 +00:00			# The `dev-dependencies` section sets up tools for building `jj`
			# documentation. `poetry` will install these in a virtual environment.
			`[tool.poetry]`
			`name = "jj-docs"`
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-12 22:30:26 +00:00			`package-mode = false`
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-18 23:43:20 +00:00
			`[tool.poetry.dependencies]`
			`python = "^3.8"`

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-03 05:47:47 +00:00			`[tool.poetry.group.dev.dependencies]`
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-02 05:45:46 +00:00			# These can be updated with `poetry add`.
docs: update dependency versions, `poetry update` 2024-05-12 21:43:10 +00:00			`mkdocs = ">=1.6,<1.7"`
update mkdocs-material & `poetry update` The new version supports showing labels in version selector. 2024-05-20 02:26:54 +00:00			`mkdocs-material = ">=9.5.24,<9.6"`
docs: update dependency versions, `poetry update` 2024-05-12 21:43:10 +00:00			`# Versioning of documentation`
			`mike = ">=2.1.1,<3"`
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-02 05:26:07 +00:00			`# (Py)Markdown extensions`
			`mdx-truly-sane-lists = "^1.3"`
			`mdx-breakless-lists = "^1.0.1"`
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-04 01:20:04 +00:00			`# Allows setting up redirects when renaming docs files`
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-18 23:43:20 +00:00			`mkdocs-redirects = "^1.2.1"`
docs: update dependency versions, `poetry update` 2024-05-12 21:43:10 +00:00			`# Used for the CLI reference`
poetry: add the include-markdown MkDocs plugin 2024-02-07 20:06:54 +00:00			`mkdocs-include-markdown-plugin = "^6.0.4"`