From bc7f663c34be981d0636e07ac10e3122322762e5 Mon Sep 17 00:00:00 2001 From: Craig Ferguson Date: Tue, 4 Jan 2022 11:38:28 +0000 Subject: [PATCH] Use MDX to test the README example --- README.md | 32 +++++++++++++++++++++----------- dune | 4 ++++ dune-project | 1 + examples/readme.ml | 19 ------------------- irmin.opam | 1 + 5 files changed, 27 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 9623cd6ffc..df4736660c 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,7 @@ version and install instructions on [ocaml.org](https://ocaml.org/docs/install.h To install Irmin with the command-line tool and all optional dependencies using `opam`: + ```bash opam install irmin-unix ``` @@ -58,6 +59,7 @@ To install Irmin with the command-line tool and all optional dependencies using A minimal installation containing the reference in-memory backend can be installed by running: + ```bash opam install irmin ``` @@ -79,6 +81,7 @@ The following packages have been made available on `opam`: To install a specific package, simply run: + ```bash opam install ``` @@ -88,6 +91,7 @@ To install a specific package, simply run: To install the development version of Irmin in your current `opam switch`, clone this repository and `opam install` the packages inside: + ```bash git clone https://github.com/mirage/irmin cd irmin/ @@ -101,12 +105,12 @@ this repository and `opam install` the packages inside: Below is a simple example of setting a key and getting the value out of a Git-based, filesystem-backed store. - + ```ocaml open Lwt.Syntax (* Irmin store with string contents *) -module Store = Irmin_unix.Git.FS.KV(Irmin.Contents.String) +module Store = Irmin_unix.Git.FS.KV (Irmin.Contents.String) (* Database configuration *) let config = Irmin_git.config ~bare:true "/tmp/irmin/test" @@ -126,12 +130,12 @@ let main = (* Set key "foo/bar" to "testing 123" *) let* () = - Store.set_exn t ~info:(info "Updating foo/bar") ["foo"; "bar"] + Store.set_exn t ~info:(info "Updating foo/bar") [ "foo"; "bar" ] "testing 123" in (* Get key "foo/bar" and print it to stdout *) - let+ x = Store.get t ["foo"; "bar"] in + let+ x = Store.get t [ "foo"; "bar" ] in Printf.printf "foo/bar => '%s'\n" x (* Run the program *) @@ -141,9 +145,12 @@ let () = Lwt_main.run main The example is contained in [examples/readme.ml](./examples/readme.ml) It can be compiled and executed with dune: - $ dune build examples/readme.exe - $ dune exec examples/readme.exe - foo/bar => 'testing 123' + +```bash +$ dune build examples/readme.exe +$ dune exec examples/readme.exe +foo/bar => 'testing 123' +``` The [examples](./examples/) directory also contains more advanced examples, which can be executed in the same way. @@ -153,10 +160,13 @@ which can be executed in the same way. The same thing can also be accomplished using `irmin`, the command-line application installed with `irmin-unix`, by running: - $ echo "root: ." > irmin.yml - $ irmin init - $ irmin set foo/bar "testing 123" - $ irmin get foo/bar +```bash +$ echo "root: ." > irmin.yml +$ irmin init +$ irmin set foo/bar "testing 123" +$ irmin get foo/bar +testing 123 +``` `irmin.yml` allows for `irmin` flags to be set on a per-directory basis. You can also set flags globally using `$HOME/.irmin/config.yml`. Run diff --git a/dune b/dune index 07287393eb..fa44a809ce 100644 --- a/dune +++ b/dune @@ -1 +1,5 @@ (vendored_dirs vendors) + +(mdx + (files README.md) + (packages irmin irmin-unix)) diff --git a/dune-project b/dune-project index 2a48fb249e..736ae08ec9 100644 --- a/dune-project +++ b/dune-project @@ -2,3 +2,4 @@ (name irmin) (allow_approximate_merlin) (cram enable) +(using mdx 0.1) diff --git a/examples/readme.ml b/examples/readme.ml index 7c88d4414c..f419eaca43 100644 --- a/examples/readme.ml +++ b/examples/readme.ml @@ -1,22 +1,3 @@ -(* - * Copyright (c) 2013-2021 Thomas Gazagnaire - * - * Permission to use, copy, modify, and distribute this software for any - * purpose with or without fee is hereby granted, provided that the above - * copyright notice and this permission notice appear in all copies. - * - * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR - * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF - * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - *) - -(* N.B. This excerpt is extracted from project README. Any changes made here - * should be mirrored there. *) - open Lwt.Syntax (* Irmin store with string contents *) diff --git a/irmin.opam b/irmin.opam index f7fd873c4c..a7c66580d4 100644 --- a/irmin.opam +++ b/irmin.opam @@ -33,6 +33,7 @@ depends: [ "alcotest" {>= "1.1.0" & with-test} "alcotest-lwt" {with-test} "vector" {with-test} + "mdx" {>= "2.0.0" & with-test} "odoc" {(< "2.0.1" | > "2.0.2") & with-doc} # See https://github.com/ocaml/odoc/issues/793 ]