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.

.gitattributes

@@ -1,2 +1,3 @@
 Cargo.lock linguist-generated=true merge=binary
 flake.lock linguist-generated=true merge=binary
+poetry.lock linguist-generated=true merge=binary

.github/workflows/codespell.yml

@@ -18,5 +18,5 @@ jobs:
         with:
           check_filenames: true
           check_hidden: true
-          skip: target,.jj
+          skip: target,.jj,*.lock
           ignore_words_list: crate,nd,nD

.gitignore

@@ -1,4 +1,5 @@
 /target/
+/rendered-docs
 .direnv
 .envrc
 # generated by nix build, nix-build

docs/contributing.md

@@ -64,6 +64,9 @@ excellent resources at https://www.rust-lang.org/learn, we recommend the
 ["Comprehensive Rust" mini-course](https://google.github.io/comprehensive-rust/)
 for an overview, especially if you are familiar with C++.
 
+<!--- TODO: A section asking for people to report documentation bugs and
+ ---- asking them to check if the problem exists in the prerelease docs.
+ ---->
 
 ## Setting up a development environment
 
@@ -131,7 +134,60 @@ These are listed roughly in order of decreasing importance.
    use `nextest` with `insta`,
    use `cargo insta test --workspace --test-runner nextest`.
 
- ## Modifying protobuffers (this is not common)
+## Previewing the HTML documentation
+
+<!---- Short-term TODO: More docs follow in a subsequent commit ---->
+
+### Setting up the prerequisites
+
+To build the website, you must have Python and `poetry` installed. If
+your distribution packages `poetry`, something like `apt install
+python3-poetry` is likely the best way to install it. Otherwise, you
+can download Python from <https://python.org> or follow the [Python
+installation instructions]. Finally, follow the [Poetry installation
+instructions].
+
+[Python installation instructions]: https://docs.python.org/3/using/index.html
+[Poetry installation instructions]: https://python-poetry.org/docs/#installation 
+
+Once you have `poetry` installed, you should ask it to install the rest
+of the required tools into a virtual environment as follows:
+
+```shell
+poetry install
+```
+
+If you get requests to "unlock a keyring" or error messages about failing to do
+so, this is a [known `poetry`
+bug](https://github.com/python-poetry/poetry/issues/1917). The workaround is to
+run the following and then to try `poetry install` again:
+
+```shell
+# For sh-compatible shells or recent versions of `fish`
+export PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring
+```
+
+### Building the HTML docs locally (with live reload)
+
+The HTML docs are built with [MkDocs](https://github.com/mkdocs/mkdocs). After
+following the above steps, you should be able to view the docs by running
+
+```shell
+# Note: this and all the commands below should be run from the root of
+# the `jj` source tree.
+poetry run -- mkdocs serve
+```
+
+and opening <http://127.0.0.1:8000> in your browser.
+
+As you edit the `md` files, the website should be rebuilt and reloaded in your
+browser automatically, unless build errors occur.
+
+You should occasionally check the terminal from which you ran `mkdocs serve` for
+any build errors or warnings. Warnings about `"GET /versions.json HTTP/1.1" code
+404` are expected and harmless.
+
+## Modifying protobuffers (this is not common)
 
  Occasionally, you may need to change the `.proto` files that define jj's data
  storage format. In this case, you will need to add a few steps to the above

mkdocs.yml

@@ -0,0 +1,80 @@
+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
+extra:
+  version:
+    provider: mike
+plugins:
+    - search
+    - redirects:
+        redirect_maps:
+            'index.md': 'install-and-setup.md'
+
+# 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
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.superfences
+  - pymdownx.details
+  - pymdownx.snippets
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+
+# This lists all the files that become part of the documentation
+nav:
+- 'Getting started':
+      - 'Installation and Setup': 'install-and-setup.md'
+      - 'Tutorial and Birds-Eye View': 'tutorial.md'
+      - 'Working with Github': 'github.md'
+
+- FAQ: 'FAQ.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'
+    - 'Tracking branches': 'design/tracking-branches.md'
+
+