mirrors/jj
1
0
Fork 1
mirror of https://github.com/martinvonz/jj.git synced 2024-11-24 06:19:42 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 12
jj/mkdocs.yml

145 lines
4.6 KiB
YAML
Raw Permalink Normal View History

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
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
docs: Make the website's theme adjustable. The website will also adjust to the system default theme now. I mostly did this because I am a darkkmode user and we didn't provide it yet.
2024-01-02 21:14:57 +00:00
docs: add copy tracking design doc to MkDocs Missed in #3574.
2024-07-19 18:10:54 +00:00
# Respect the user's default settings and add a toggle for manually choosing
docs: Make the website's theme adjustable. The website will also adjust to the system default theme now. I mostly did this because I am a darkkmode user and we didn't provide it yet.
2024-01-02 21:14:57 +00:00
# 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
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
extra:
version:
provider: mike
docs: show version alias in version selector See https://github.com/martinvonz/jj/pull/3723 for a screenshot. This will make it clearer to the users that the "latest" and "v0.??.?" are the same even if the former does not redirect to the latter (but has identical contents). MkDocs material lists the *first* alias for each version, so I also added a "nightly" alias for "prerelease". Otherwise, users would see the "main" alias, and might get confused whether they should use "latest" or "main" docs if they don't realize it's named after the "main" branch. (Upon testing, it still shows "main" for now, but it should be possible to fix this after this PR is merged by reordering the aliases directly in `versions.json` on the gh-pages branch)
2024-05-20 02:27:50 +00:00
alias: true
docs: fix a bug with offline docs generation This is a rather annoying bug. It was revealed because CLI reference stopped working for *offline* docs after the previous commit. Turns out, none of the plugins we enabled for normal docs were turned on in `mkdocs-offline.yml`. Thanks to @mondeja for figuring out what was going on. In the future, we could try a less ugly fix, e.g. turning the `offline` plugin on or off via an environment variable. See also: https://github.com/squidfunk/mkdocs-material/issues/6749 https://github.com/mondeja/mkdocs-include-markdown-plugin/issues/195#issuecomment-1933085478
2024-02-07 22:09:29 +00:00
docs: ask MkDocs to fail on links to non-existent sections This also requires anchors to be lower-cased: https://github.com/mkdocs/mkdocs/issues/3703
2024-05-06 22:54:55 +00:00
validation:
anchors: warn
docs: fix a bug with offline docs generation This is a rather annoying bug. It was revealed because CLI reference stopped working for *offline* docs after the previous commit. Turns out, none of the plugins we enabled for normal docs were turned on in `mkdocs-offline.yml`. Thanks to @mondeja for figuring out what was going on. In the future, we could try a less ugly fix, e.g. turning the `offline` plugin on or off via an environment variable. See also: https://github.com/squidfunk/mkdocs-material/issues/6749 https://github.com/mondeja/mkdocs-include-markdown-plugin/issues/195#issuecomment-1933085478
2024-02-07 22:09:29 +00:00
# IMPORTANT: any changes to plugins have to be duplicated in
# `mkdocs-offline.yml`. See that file for more details.
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
plugins:
docs: set canonical_version to latest Currently, https://www.google.com/search?q=jj+revsets has problematic results, one of the top links for me is https://martinvonz.github.io/jj/v0.14.0/github/ (we are currently on v0.17.1). I hope this will help them all point to `latest` instead.
2024-05-20 01:17:05 +00:00
- mike:
# Should help search engines point to latest docs
# instead of (often obsolete) v?.??.? docs.
# TODO: Arguably, this could be `prerelease` when building prerelease docs.
canonical_version: latest
poetry: add the include-markdown MkDocs plugin
2024-02-07 20:06:54 +00:00
- include-markdown # For the CLI reference
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
- search
- redirects:
redirect_maps:
docs website & mkdocs.yml: redirect `/branches/` URL After this is merged, https://martinvonz.github.io/jj/prerelease/branches/ should redirect to https://martinvonz.github.io/jj/prerelease/bookmarks/ instead of resulting in a 404 error and old links to docs (from posts or from Google index) breaking.
2024-09-16 06:15:56 +00:00
branches.md: bookmarks.md
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
# 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
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
# 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
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
- pymdownx.tabbed:
alternate_style: true
docs: add mermaid plugin for diagrams
2023-11-22 15:10:40 +00:00
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
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
- pymdownx.details
- pymdownx.snippets
- pymdownx.emoji:
poetry: run `poetry update`, remove warnings from new mkdocs-material
2023-11-02 05:45:46 +00:00
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
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
# This lists all the files that become part of the documentation
nav:
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
- 'Home': 'index.md'
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
- 'Getting started':
- 'Installation and Setup': 'install-and-setup.md'
- 'Tutorial and Birds-Eye View': 'tutorial.md'
docs: goodbye Github, hello GitHub
2023-08-28 17:30:33 +00:00
- 'Working with GitHub': 'github.md'
docs: add notes for Windows users
2024-01-27 19:56:36 +00:00
- 'Working on Windows': 'windows.md'
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
- FAQ: 'FAQ.md'
docs: store output of `jj util markdown-help`, render it on the website 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
2024-01-28 03:31:27 +00:00
- "CLI Reference": 'cli-reference.md'
docs: Add a Testmonials page. Show our positive reviews to the world. It's also not completly serious, in a similar fashion to Phabricator. Co-Authored-By: Austin Seipp <aseipp@pobox.com>
2024-02-09 18:36:19 +00:00
- Testimonials: 'testimonials.md'
docs: hyphenate "community-built"
2024-06-19 20:21:34 +00:00
- "Community-built tools": 'community_tools.md'
docs: Add a page for community built tools. Thank you all for building tools around it.
2024-05-18 17:06:59 +00:00
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
- Concepts:
- 'Working Copy': 'working-copy.md'
everything: Rename `branches` to `bookmarks` Jujutsu's branches do not behave like Git branches, which is a major hurdle for people adopting it from Git. They rather behave like Mercurial's (hg) bookmarks. We've had multiple discussions about it in the last ~1.5 years about this rename in the Discord, where multiple people agreed that this _false_ familiarity does not help anyone. Initially we were reluctant to do it but overtime, more and more users agreed that `bookmark` was a better for name the current mechanism. This may be hard break for current `jj branch` users, but it will immensly help Jujutsu's future, by defining it as our first own term. The `[experimental-moving-branches]` config option is currently left alone, to force not another large config update for users, since the last time this happened was when `jj log -T show` was removed, which immediately resulted in breaking users and introduced soft deprecations. This name change will also make it easier to introduce Topics (#3402) as _topological branches_ with a easier model. This was mostly done via LSP, ripgrep and sed and a whole bunch of manual changes either from me being lazy or thankfully pointed out by reviewers.
2024-08-21 19:59:15 +00:00
- 'Bookmarks': 'bookmarks.md'
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
- 'Conflicts': 'conflicts.md'
- 'Operation Log': 'operation-log.md'
- 'Glossary': 'glossary.md'
- 'Configuration':
- 'Settings': 'config.md'
fileset: add basic pattern parsing functions Naming convention is described in FilePattern::from_str_kind(). It's based on Mercurial's pattern prefixes, but hopefully fixes some inconsistencies. https://github.com/martinvonz/jj/issues/2915#issuecomment-1956401114 #3239
2024-04-05 12:39:59 +00:00
- 'Fileset language': 'filesets.md'
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
- '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'
docs: Formalize our design docs process a bit. This adds the basic outline of _when_ a Design Doc should be written. See the next commit in the stack for the blueprint. By adding this we hopefully can prevent unnecessary churn from new and longtime contributors, when they want to add a major feature or rewrite a core part of Jujutsu. The text is written as a guideline, not a rule.
2024-06-17 20:17:16 +00:00
- 'Design Docs': 'design_docs.md'
docs: Add a Design Doc blueprint. This should be the template for all new Design Docs, minor deviations aside. Hopefully this makes the process a bit easier.
2024-06-17 20:30:36 +00:00
- 'Design Doc Blueprint': 'design_doc_blueprint.md'
docs: introduce temporary governance voting process In order for the governance working group to make progress establishing jj's governance structure, we need the approval of the jj community. Set up a temporary voting process to get that approval. Additionally, set up a governance dir for other governance-related documentation to sit in. Later, when we have a permanent governance structure and enough policy to let the community make changes without needing the governance working group, we can delete this document.
2024-09-05 22:33:01 +00:00
- 'Temporary Voting for Governance': 'governance/temporary-voting.md'
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
docs: add copy tracking design doc to MkDocs Missed in #3574.
2024-07-19 18:10:54 +00:00
- 'Design docs':
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
- 'git-submodules': 'design/git-submodules.md'
- 'git-submodule-storage': 'design/git-submodule-storage.md'
docs/design: Move the `run` doc to github. This ticks another box in #1869. Co-Authored-By: arxanas <me@waleedkhan.name> Co-Authored-By: hooper <hooper@google.com> Co-Authored-By: martinvonz <martinvonz@google.com>
2023-09-05 22:49:59 +00:00
- 'JJ run': 'design/run.md'
sparse-v2: design doc proposition for Sparse Patterns refactoring Kicks off work on issue #1896
2024-01-23 17:53:07 +00:00
- 'Sparse Patterns v2': 'design/sparse-v2.md'
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
- 'Tracking branches': 'design/tracking-branches.md'
docs: add copy tracking design doc to MkDocs Missed in #3574.
2024-07-19 18:10:54 +00:00
- 'Copy tracking and tracing': 'design/copy-tracking.md'
docs: Make the Roadmap a toplevel website entry This also fixes the Xethub link, by pointing it to the web archive, which no longer is available.
2024-11-14 21:30:11 +00:00
- 'Development Roadmap': "roadmap.md"
Reference in a new issue Copy permalink