Commit graph

24 commits

Author SHA1 Message Date
Philip Metzger
3b2197c74a 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-30 15:37:40 +02:00
Philip Metzger
c4777e4721 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-30 15:37:40 +02:00
Martin von Zweigbergk
31b8f07fa0 docs: hyphenate "community-built" 2024-06-20 05:34:02 +09:00
Philip Metzger
30f54862dd docs: Add a page for community built tools.
Thank you all for building tools around it.
2024-06-17 19:47:13 +02:00
Ilya Grigoriev
864869abd5 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-21 16:19:04 -07:00
Ilya Grigoriev
ff810c6097 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-21 16:19:04 -07:00
Ilya Grigoriev
c9b44f3828 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-14 13:14:27 -07:00
Yuya Nishihara
850887cf09 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-07 19:43:29 +09:00
Philip Metzger
5b0ef324d1 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-25 14:20:33 +01:00
Ilya Grigoriev
44e1d4a72d 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-12 10:28:09 -08:00
Ilya Grigoriev
b170988a46 poetry: add the include-markdown MkDocs plugin 2024-02-12 10:28:09 -08:00
Daniel Ploch
01825953ac sparse-v2: design doc proposition for Sparse Patterns refactoring
Kicks off work on issue #1896
2024-02-01 16:02:14 -08:00
Ilya Grigoriev
52c415eaf4 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-30 14:58:32 -08:00
Stephen Jennings
b2800f7f44 docs: add notes for Windows users 2024-01-29 12:16:15 -08:00
Philip Metzger
e79fd2e81c 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-07 22:07:24 +01:00
Carlos Precioso
5568ca81c6 docs: add mermaid plugin for diagrams 2023-11-22 10:38:57 -08:00
Ilya Grigoriev
f62293d218 poetry: run poetry update, remove warnings from new mkdocs-material 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
dbbed2d2a5 docs: restore directory structure of the website
The `offline` plugin added to the MkDocs config in commit 772e2b8 ended up
changing the directory structure of the website, see the resulting commit
56aec196.

**Before** that commit, the following URLs were valid:

<https://martinvonz.github.io/jj/v0.9.0/revsets>
<https://martinvonz.github.io/jj/v0.9.0/revsets/>

and <https://martinvonz.github.io/jj/v0.9.0/revsets.html> was invalid.

The situation described above should be restored by this commit.

**After** 772e2b8 and before this commit, the following URLs were valid:

<https://martinvonz.github.io/jj/v0.9.0/revsets>
<https://martinvonz.github.io/jj/v0.9.0/revsets.html> and
<https://martinvonz.github.io/jj/v0.9.0/revsets/> was invalid.

This commit is likely to break the version switcher between v0.9.0 and newer
versions. The breakage would be minimized if this is merged shortly before a
release (but with enough time to test it out). Alternatively, I could try to
fix up the docs for that version.

We could also consciously decide to leave things as they are now.

The problem was noticed by @hooper, who noticed URLs in their browser history
that were no longer valid.
2023-10-02 20:40:23 -07:00
Philip Metzger
5b729a90a9 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-14 16:39:40 +02:00
Ilya Grigoriev
772e2b8be6 GitHub release action: publish HTML docs in an archive 2023-08-31 20:44:08 -07:00
Ilya Grigoriev
b67c115c29 docs: goodbye Github, hello GitHub 2023-08-28 10:43:48 -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