mirror of
https://github.com/martinvonz/jj.git
synced 2024-10-23 06:57:32 +00:00
52c415eaf4
I am using a very hacky approach, using `insta` to generate the markdown help. This is based on a lucky coincidence that `insta` chose to use a header format for snapshot files that MkDocs interprets as a Markdown header (and ignores). I considered several other approaches, but I couldn't resist the facts that: - This doesn't require new developers to install any extra tools or run any extra commands. - There is no need for a new CI check. - There is no need to compile `jj` in the "Make HTML docs" GitHub action, which is currently very fast and cheap. Downside: I'm not sure how well MkDocs will work on Windows, unless the developer explicitly enables symbolic links (which IIUC is not trivial). ### Possible alternatives My next favorite approaches (which we could switch to later) would be: #### `xtask` Set up a CI check and a [Cargo `xtask`] so that `cargo xtask cli-help-to-md` essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from the project root. Every developer would have to know to run `cargo xtask cli-help-to-md` if they change the help text. Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`. #### Only generate markdown for CLI help when building the website, don't track it in Git. I think that having the file in the repo will be nice to preview changes to docs, and it'll allow people to consult the file on GitHub or in their repo. The (currently) very fast job of building the website would now require installing Rust and building `jj`. #### Same as the `xtask`, but use a shell script instead of an `xtask` An `xtask` might seem like overkill, since it's Rust instead of a shell script. However, I don't want this to be a shell script so that new contributors on Windows can still easily run it ( since this will be necessary for the CI to pass) without us having to support a batch file. #### Cargo Alias My first attempt was to set up a [cargo alias] to run this, but that doesn't support redirection (so I had to change the `jj util` command to output to a file) and, worse, is incapable of executing the command *in the project root* regardless of where in the project the current directory is. Again, this seems to be too inconvenient for a command that every new PR author would have to run to pass CI. Overall, this just seems a bit ugly. I did file https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was worthwhile, though. **Aside:** For reference, the alias was: ```toml # .cargo/config.toml alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md" ``` ### Non-alternatives #### Clap's new feature `clap` recently obtained a similarly-sounding feature in https://github.com/clap-rs/clap/pull/5206. However, it only prints short help for subcommands and can't be triggered by an option AFAICT, so it won't help us too much. [Cargo `xtask`]: https://github.com/matklad/cargo-xtask [cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias
121 lines
3.6 KiB
YAML
121 lines
3.6 KiB
YAML
site_name: Jujutsu docs
|
|
site_dir: 'rendered-docs'
|
|
# Not having this (or viewing the site locally, or from any place other than the
|
|
# site_url) leads to version switching failing to preserve the current path.
|
|
site_url: !ENV [SITE_URL_FOR_MKDOCS, 'https://martinvonz.github.io/jj/']
|
|
theme:
|
|
name: 'material'
|
|
language: 'en'
|
|
features:
|
|
# - navigation.top
|
|
|
|
# Respect the users default settings and add a toggle for manually choosing
|
|
# automatic/light/dark palette.
|
|
# taken from https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#system-preference
|
|
palette:
|
|
- media: "(prefers-color-scheme)"
|
|
toggle:
|
|
icon: material/brightness-auto
|
|
name: Switch to system preference
|
|
- media: "(prefers-color-scheme: light)"
|
|
scheme: default
|
|
toggle:
|
|
icon: material/brightness-7
|
|
name: Switch to light mode
|
|
- media: "(prefers-color-scheme: dark)"
|
|
scheme: slate
|
|
toggle:
|
|
icon: material/brightness-4
|
|
name: Switch to dark mode
|
|
|
|
extra:
|
|
version:
|
|
provider: mike
|
|
plugins:
|
|
- search
|
|
- redirects:
|
|
redirect_maps:
|
|
|
|
# Not all of these may be necessary, especially since the material
|
|
# theme substitutes for some of them
|
|
markdown_extensions:
|
|
- toc:
|
|
permalink: true
|
|
- extra
|
|
- sane_lists
|
|
- 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:
|
|
custom_fences:
|
|
- name: mermaid
|
|
class: mermaid
|
|
format: !!python/name:pymdownx.superfences.fence_code_format
|
|
- pymdownx.details
|
|
- pymdownx.snippets
|
|
- pymdownx.emoji:
|
|
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
|
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
|
|
|
# This lists all the files that become part of the documentation
|
|
nav:
|
|
- 'Home': 'index.md'
|
|
|
|
- 'Getting started':
|
|
- 'Installation and Setup': 'install-and-setup.md'
|
|
- 'Tutorial and Birds-Eye View': 'tutorial.md'
|
|
- 'Working with GitHub': 'github.md'
|
|
- 'Working on Windows': 'windows.md'
|
|
|
|
- FAQ: 'FAQ.md'
|
|
|
|
- "CLI Reference": 'cli-reference.md'
|
|
|
|
- Concepts:
|
|
- 'Working Copy': 'working-copy.md'
|
|
- 'Branches': 'branches.md'
|
|
- 'Conflicts': 'conflicts.md'
|
|
- 'Operation Log': 'operation-log.md'
|
|
- 'Glossary': 'glossary.md'
|
|
|
|
- 'Configuration':
|
|
- 'Settings': 'config.md'
|
|
- 'Revset language': 'revsets.md'
|
|
- 'Templating language': 'templates.md'
|
|
|
|
- 'Comparisons':
|
|
- 'Git comparison': 'git-comparison.md'
|
|
- 'Git compatibility': 'git-compatibility.md'
|
|
- 'Sapling': 'sapling-comparison.md'
|
|
- 'Other related work': 'related-work.md'
|
|
|
|
- 'Technical details':
|
|
- 'Architecture': 'technical/architecture.md'
|
|
- 'Concurrency': 'technical/concurrency.md'
|
|
- 'Conflicts': 'technical/conflicts.md'
|
|
|
|
- Contributing:
|
|
- 'Guidelines and "How to...?"': 'contributing.md'
|
|
- 'Code of conduct': 'code-of-conduct.md'
|
|
|
|
- 'Design docs':
|
|
- 'git-submodules': 'design/git-submodules.md'
|
|
- 'git-submodule-storage': 'design/git-submodule-storage.md'
|
|
- 'JJ run': 'design/run.md'
|
|
- 'Tracking branches': 'design/tracking-branches.md'
|
|
|
|
|