ok/jj
1
0
Fork 0
forked from mirrors/jj

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.
This commit is contained in:
Ilya Grigoriev 2023-11-01 22:26:07 -07:00
parent 5973ab47b9
commit adc8433204
5 changed files with 102 additions and 55 deletions

View file

@ -78,74 +78,95 @@ You can also specify revisions by using functions. Some functions take other
revsets (expressions) as arguments.
* `parents(x)`: Same as `x-`.
* `children(x)`: Same as `x+`.
* `ancestors(x[, depth])`: `ancestors(x)` is the same as `::x`.
`ancestors(x, depth)` returns the ancestors of `x` limited to the given
* `ancestors(x[, depth])`: `ancestors(x)` is the same as `::x`.
`ancestors(x, depth)` returns the ancestors of `x` limited to the given
`depth`.
* `descendants(x)`: Same as `x::`.
* `connected(x)`: Same as `x::x`. Useful when `x` includes several commits.
* `all()`: All visible commits in the repo.
* `none()`: No commits. This function is rarely useful; it is provided for
completeness.
* `branches([pattern])`: All local branch targets. If `pattern` is specified,
this selects the branches whose name match the given [string
pattern](#string-patterns). For example, `branches(push)` would match the
branches `push-123` and `repushed` but not the branch `main`. If a branch is
in a conflicted state, all its possible targets are included.
* `remote_branches([branch_pattern[, [remote=]remote_pattern]])`: All remote
branch targets across all remotes. If just the `branch_pattern` is
specified, the branches whose names match the given [string
pattern](#string-patterns) across all remotes are selected. If both
`branch_pattern` and `remote_pattern` are specified, the selection is
further restricted to just the remotes whose names match `remote_pattern`.
For example, `remote_branches(push, ri)` would match the branches
`push-123@origin` and `repushed@private` but not `push-123@upstream` or
`main@origin` or `main@upstream`. If a branch is in a conflicted state, all
its possible targets are included.
* `remote_branches([branch_pattern[, [remote=]remote_pattern]])`: All remote
branch targets across all remotes. If just the `branch_pattern` is
specified, the branches whose names match the given [string
pattern](#string-patterns) across all remotes are selected. If both
`branch_pattern` and `remote_pattern` are specified, the selection is
further restricted to just the remotes whose names match `remote_pattern`.
For example, `remote_branches(push, ri)` would match the branches
`push-123@origin` and `repushed@private` but not `push-123@upstream` or
`main@origin` or `main@upstream`. If a branch is in a conflicted state, all
its possible targets are included.
* `tags()`: All tag targets. If a tag is in a conflicted state, all its
possible targets are included.
* `git_refs()`: All Git ref targets as of the last import. If a Git ref
is in a conflicted state, all its possible targets are included.
* `git_head()`: The Git `HEAD` target as of the last import. Equivalent to
`present(HEAD@git)`.
* `visible_heads()`: All visible heads (same as `heads(all())`).
* `root()`: The virtual commit that is the oldest ancestor of all other commits.
* `heads(x)`: Commits in `x` that are not ancestors of other commits in `x`.
Note that this is different from
[Mercurial's](https://repo.mercurial-scm.org/hg/help/revsets) `heads(x)`
function, which is equivalent to `x ~ x-`.
* `roots(x)`: Commits in `x` that are not descendants of other commits in `x`.
Note that this is different from
[Mercurial's](https://repo.mercurial-scm.org/hg/help/revsets) `roots(x)`
function, which is equivalent to `x ~ x+`.
* `latest(x[, count])`: Latest `count` commits in `x`, based on committer
timestamp. The default `count` is 1.
* `merges()`: Merge commits.
* `description(pattern)`: Commits that have a description matching the given
[string pattern](#string-patterns).
* `author(pattern)`: Commits with the author's name or email matching the given
[string pattern](#string-patterns).
* `mine()`: Commits where the author's email matches the email of the current
user.
* `committer(pattern)`: Commits with the committer's name or email matching the
given [string pattern](#string-patterns).
* `empty()`: Commits modifying no files. This also includes `merges()` without
user modifications and `root()`.
* `file(relativepath)` or `file("relativepath"[, "relativepath"]...)`: Commits
modifying one of the paths specified. Currently, string patterns are *not*
supported in the path arguments.
Paths are relative to the directory `jj` was invoked from. A directory name
will match all files in that directory and its subdirectories.
For example, `file(foo)` will match files `foo`, `foo/bar`, `foo/bar/baz`.
It will *not* match `foobar` or `bar/foo`.
* `file(relativepath)` or `file("relativepath"[, "relativepath"]...)`: Commits
modifying one of the paths specified. Currently, string patterns are *not*
supported in the path arguments.
Paths are relative to the directory `jj` was invoked from. A directory name
will match all files in that directory and its subdirectories.
For example, `file(foo)` will match files `foo`, `foo/bar`, `foo/bar/baz`.
It will *not* match `foobar` or `bar/foo`.
* `conflict()`: Commits with conflicts.
* `present(x)`: Same as `x`, but evaluated to `none()` if any of the commits
in `x` doesn't exist (e.g. is an unknown branch name.)

View file

@ -25,22 +25,26 @@ Here is a list of some differences between jj and Sapling.
is [automatically snapshotted by every command](working-copy.md). New files
are automatically tracked and deleted files are automatically untracked. This
has several advantages:
* The working copy is effectively backed up every time you run a command.
* No commands fail because you have changes in the working copy ("abort: 1
conflicting file changes: ..."). No need for `sl shelve`.
* Simpler and more consistent CLI because the working copy is treated like
any other commit.
* The working copy is effectively backed up every time you run a command.
* No commands fail because you have changes in the working copy ("abort: 1
conflicting file changes: ..."). No need for `sl shelve`.
* Simpler and more consistent CLI because the working copy is treated like any
other commit.
* **Conflicts:** Like most VCSs, Sapling requires the user to
resolve conflicts before committing. jj lets
you [commit conflicts](conflicts.md). Note that it's a representation of the
conflict that's committed, not conflict markers (`<<<<<<<` etc.). This also
has several advantages:
* Merge conflicts won't prevent you from checking out another commit.
* You can resolve the conflicts when you feel like it.
* Rebasing descendants always succeeds. Like jj, Sapling automatically
rebases, but it will fail if there are conflicts.
* Merge commits can be rebased correctly (Sapling sometimes fails).
* You can rebase conflicts and conflict resolutions.
* Merge conflicts won't prevent you from checking out another commit.
* You can resolve the conflicts when you feel like it.
* Rebasing descendants always succeeds. Like jj, Sapling automatically
rebases, but it will fail if there are conflicts.
* Merge commits can be rebased correctly (Sapling sometimes fails).
* You can rebase conflicts and conflict resolutions.
* **Undo:** jj's undo is powered by [the operation log](operation-log.md), which
records how the repo has changed over time. Sapling has a similar feature
with its [MetaLog](https://sapling-scm.com/docs/internals/metalog).

View file

@ -26,6 +26,17 @@ markdown_extensions:
- admonition
- codehilite:
guess_lang: false
# Allows list items with several paragraphs to be indented two spaces instead
# of four (like GitHub markdown)
- mdx_truly_sane_lists:
# No, thanks, we'd like only somewhat sane lists :)
# With `truly_sane: true`, together with breakless lists, it often splits
# a single list in two.
truly_sane: false
# Fixes weird concatenation of list items that happens sometimes when
# there is not a paragraph break between them and one of them has
# multiple paragraphs.
- mdx_breakless_lists
- pymdownx.tabbed:
alternate_style: true
- pymdownx.superfences

52
poetry.lock generated
View file

@ -1,4 +1,4 @@
# This file is automatically @generated by Poetry 1.6.1 and should not be changed by hand.
# This file is automatically @generated by Poetry 1.5.1 and should not be changed by hand.
[[package]]
name = "babel"
@ -395,16 +395,6 @@ files = [
{file = "MarkupSafe-2.1.3-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:5bbe06f8eeafd38e5d0a4894ffec89378b6c6a625ff57e3028921f8ff59318ac"},
{file = "MarkupSafe-2.1.3-cp311-cp311-win32.whl", hash = "sha256:dd15ff04ffd7e05ffcb7fe79f1b98041b8ea30ae9234aed2a9168b5797c3effb"},
{file = "MarkupSafe-2.1.3-cp311-cp311-win_amd64.whl", hash = "sha256:134da1eca9ec0ae528110ccc9e48041e0828d79f24121a1a146161103c76e686"},
{file = "MarkupSafe-2.1.3-cp312-cp312-macosx_10_9_universal2.whl", hash = "sha256:f698de3fd0c4e6972b92290a45bd9b1536bffe8c6759c62471efaa8acb4c37bc"},
{file = "MarkupSafe-2.1.3-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:aa57bd9cf8ae831a362185ee444e15a93ecb2e344c8e52e4d721ea3ab6ef1823"},
{file = "MarkupSafe-2.1.3-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ffcc3f7c66b5f5b7931a5aa68fc9cecc51e685ef90282f4a82f0f5e9b704ad11"},
{file = "MarkupSafe-2.1.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:47d4f1c5f80fc62fdd7777d0d40a2e9dda0a05883ab11374334f6c4de38adffd"},
{file = "MarkupSafe-2.1.3-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1f67c7038d560d92149c060157d623c542173016c4babc0c1913cca0564b9939"},
{file = "MarkupSafe-2.1.3-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:9aad3c1755095ce347e26488214ef77e0485a3c34a50c5a5e2471dff60b9dd9c"},
{file = "MarkupSafe-2.1.3-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:14ff806850827afd6b07a5f32bd917fb7f45b046ba40c57abdb636674a8b559c"},
{file = "MarkupSafe-2.1.3-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8f9293864fe09b8149f0cc42ce56e3f0e54de883a9de90cd427f191c346eb2e1"},
{file = "MarkupSafe-2.1.3-cp312-cp312-win32.whl", hash = "sha256:715d3562f79d540f251b99ebd6d8baa547118974341db04f5ad06d5ea3eb8007"},
{file = "MarkupSafe-2.1.3-cp312-cp312-win_amd64.whl", hash = "sha256:1b8dd8c3fd14349433c79fa8abeb573a55fc0fdd769133baac1f5e07abf54aeb"},
{file = "MarkupSafe-2.1.3-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:8e254ae696c88d98da6555f5ace2279cf7cd5b3f52be2b5cf97feafe883b58d2"},
{file = "MarkupSafe-2.1.3-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cb0932dc158471523c9637e807d9bfb93e06a95cbf010f1a38b98623b929ef2b"},
{file = "MarkupSafe-2.1.3-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9402b03f1a1b4dc4c19845e5c749e3ab82d5078d16a2a4c2cd2df62d57bb0707"},
@ -437,6 +427,34 @@ files = [
{file = "MarkupSafe-2.1.3.tar.gz", hash = "sha256:af598ed32d6ae86f1b747b82783958b1a4ab8f617b06fe68795c7f026abbdcad"},
]
[[package]]
name = "mdx-breakless-lists"
version = "1.0.1"
description = "Python Markdown package extension to allow lists without a preceding empty line."
optional = false
python-versions = "*"
files = [
{file = "mdx_breakless_lists-1.0.1-py3-none-any.whl", hash = "sha256:d49209a42561142b1dacea6821a3899a8ccd17a45da5e7e04294aa23d98d76c8"},
{file = "mdx_breakless_lists-1.0.1.tar.gz", hash = "sha256:2ec7978048673ad7cb8042b5787420a9d252053908dcb3418708cf2f91a6a538"},
]
[package.dependencies]
markdown = ">=3.0"
[[package]]
name = "mdx-truly-sane-lists"
version = "1.3"
description = "Extension for Python-Markdown that makes lists truly sane. Custom indents for nested lists and fix for messy linebreaks."
optional = false
python-versions = "*"
files = [
{file = "mdx_truly_sane_lists-1.3-py3-none-any.whl", hash = "sha256:b9546a4c40ff8f1ab692f77cee4b6bfe8ddf9cccf23f0a24e71f3716fe290a37"},
{file = "mdx_truly_sane_lists-1.3.tar.gz", hash = "sha256:b661022df7520a1e113af7c355c62216b384c867e4f59fb8ee7ad511e6e77f45"},
]
[package.dependencies]
Markdown = ">=2.6"
[[package]]
name = "mergedeep"
version = "1.3.4"
@ -686,7 +704,6 @@ files = [
{file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:69b023b2b4daa7548bcfbd4aa3da05b3a74b772db9e23b982788168117739938"},
{file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:81e0b275a9ecc9c0c0c07b4b90ba548307583c125f54d5b6946cfee6360c733d"},
{file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ba336e390cd8e4d1739f42dfe9bb83a3cc2e80f567d8805e11b46f4a943f5515"},
{file = "PyYAML-6.0.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:326c013efe8048858a6d312ddd31d56e468118ad4cdeda36c719bf5bb6192290"},
{file = "PyYAML-6.0.1-cp310-cp310-win32.whl", hash = "sha256:bd4af7373a854424dabd882decdc5579653d7868b8fb26dc7d0e99f823aa5924"},
{file = "PyYAML-6.0.1-cp310-cp310-win_amd64.whl", hash = "sha256:fd1592b3fdf65fff2ad0004b5e363300ef59ced41c2e6b3a99d4089fa8c5435d"},
{file = "PyYAML-6.0.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:6965a7bc3cf88e5a1c3bd2e0b5c22f8d677dc88a455344035f03399034eb3007"},
@ -694,15 +711,8 @@ files = [
{file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:42f8152b8dbc4fe7d96729ec2b99c7097d656dc1213a3229ca5383f973a5ed6d"},
{file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:062582fca9fabdd2c8b54a3ef1c978d786e0f6b3a1510e0ac93ef59e0ddae2bc"},
{file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d2b04aac4d386b172d5b9692e2d2da8de7bfb6c387fa4f801fbf6fb2e6ba4673"},
{file = "PyYAML-6.0.1-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:e7d73685e87afe9f3b36c799222440d6cf362062f78be1013661b00c5c6f678b"},
{file = "PyYAML-6.0.1-cp311-cp311-win32.whl", hash = "sha256:1635fd110e8d85d55237ab316b5b011de701ea0f29d07611174a1b42f1444741"},
{file = "PyYAML-6.0.1-cp311-cp311-win_amd64.whl", hash = "sha256:bf07ee2fef7014951eeb99f56f39c9bb4af143d8aa3c21b1677805985307da34"},
{file = "PyYAML-6.0.1-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:855fb52b0dc35af121542a76b9a84f8d1cd886ea97c84703eaa6d88e37a2ad28"},
{file = "PyYAML-6.0.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:40df9b996c2b73138957fe23a16a4f0ba614f4c0efce1e9406a184b6d07fa3a9"},
{file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6c22bec3fbe2524cde73d7ada88f6566758a8f7227bfbf93a408a9d86bcc12a0"},
{file = "PyYAML-6.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8d4e9c88387b0f5c7d5f281e55304de64cf7f9c0021a3525bd3b1c542da3b0e4"},
{file = "PyYAML-6.0.1-cp312-cp312-win32.whl", hash = "sha256:d483d2cdf104e7c9fa60c544d92981f12ad66a457afae824d146093b8c294c54"},
{file = "PyYAML-6.0.1-cp312-cp312-win_amd64.whl", hash = "sha256:0d3304d8c0adc42be59c5f8a4d9e3d7379e6955ad754aa9d6ab7a398b59dd1df"},
{file = "PyYAML-6.0.1-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:50550eb667afee136e9a77d6dc71ae76a44df8b3e51e41b77f6de2932bfe0f47"},
{file = "PyYAML-6.0.1-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1fe35611261b29bd1de0070f0b2f47cb6ff71fa6595c077e42bd0c419fa27b98"},
{file = "PyYAML-6.0.1-cp36-cp36m-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:704219a11b772aea0d8ecd7058d0082713c3562b4e271b849ad7dc4a5c90c13c"},
@ -719,7 +729,6 @@ files = [
{file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a0cd17c15d3bb3fa06978b4e8958dcdc6e0174ccea823003a106c7d4d7899ac5"},
{file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:28c119d996beec18c05208a8bd78cbe4007878c6dd15091efb73a30e90539696"},
{file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7e07cbde391ba96ab58e532ff4803f79c4129397514e1413a7dc761ccd755735"},
{file = "PyYAML-6.0.1-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:49a183be227561de579b4a36efbb21b3eab9651dd81b1858589f796549873dd6"},
{file = "PyYAML-6.0.1-cp38-cp38-win32.whl", hash = "sha256:184c5108a2aca3c5b3d3bf9395d50893a7ab82a38004c8f61c258d4428e80206"},
{file = "PyYAML-6.0.1-cp38-cp38-win_amd64.whl", hash = "sha256:1e2722cc9fbb45d9b87631ac70924c11d3a401b2d7f410cc0e3bbf249f2dca62"},
{file = "PyYAML-6.0.1-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:9eb6caa9a297fc2c2fb8862bc5370d0303ddba53ba97e71f08023b6cd73d16a8"},
@ -727,7 +736,6 @@ files = [
{file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5773183b6446b2c99bb77e77595dd486303b4faab2b086e7b17bc6bef28865f6"},
{file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:b786eecbdf8499b9ca1d697215862083bd6d2a99965554781d0d8d1ad31e13a0"},
{file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:bc1bf2925a1ecd43da378f4db9e4f799775d6367bdb94671027b73b393a7c42c"},
{file = "PyYAML-6.0.1-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:04ac92ad1925b2cff1db0cfebffb6ffc43457495c9b3c39d3fcae417d7125dc5"},
{file = "PyYAML-6.0.1-cp39-cp39-win32.whl", hash = "sha256:faca3bdcf85b2fc05d06ff3fbc1f83e1391b3e724afa3feba7d13eeab355484c"},
{file = "PyYAML-6.0.1-cp39-cp39-win_amd64.whl", hash = "sha256:510c9deebc5c0225e8c96813043e62b680ba2f9c50a08d3724c7f28a747d1486"},
{file = "PyYAML-6.0.1.tar.gz", hash = "sha256:bfdf460b1736c775f2ba9f6a92bca30bc2095067b8a9d77876d1fad6cc3b4a43"},
@ -990,4 +998,4 @@ testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "p
[metadata]
lock-version = "2.0"
python-versions = "^3.8"
content-hash = "0f4f1030c3b35186c9cdc94aa24719ff3093271784b61460df75d8581172880e"
content-hash = "ed47d9f5a357b3fa022d416076e2f998dc90595a367de566ff6b2005f89e67fc"

View file

@ -13,6 +13,9 @@ python = "^3.8"
[tool.poetry.dev-dependencies]
mkdocs = "^1.5.2"
mkdocs-material = "^9.2.5"
# (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"
# Versioning of documentation