Use mdexp

.github/workflows/ci.yml

@@ -31,6 +31,12 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
+      - name: Setup mdexp
+        uses: mbarbin/mdexp-actions/setup-mdexp@42da13e622de9559da363ef5906ffde63a982efd # v1.0.0-alpha.1
+        with:
+          mdexp-version: 0.0.20260315
+          mdexp-digest: sha256:f4fc53bcaa50c9dd979b968804c38322b9b7e6aa699d9d6d2d1f101965332018
+
       - name: Environment setup
         run: |
           echo "DUNE_WORKSPACE=$PWD/dune-workspace-${{ matrix.ocaml-version }}" >> "$GITHUB_ENV"

.gitignore

@@ -2,3 +2,4 @@ _opam
 _build
 _coverage
 *.install
+coverage.sh

.ocamlformat

@@ -1,3 +1,3 @@
-version=0.28.1
+version=0.29.0
 profile=janestreet
 parse-docstrings=true

README.md

@@ -27,7 +27,7 @@ We extend our deepest gratitude to the following projects and their contributors
 - [setup-dune](https://github.com/ocaml-dune/setup-dune): For seting up OCaml environments in our CI workflows.
 - [setup-ocaml](https://github.com/ocaml/setup-ocaml): Another OCaml CI tool we also used to work on the repo.
 - [odoc](https://github.com/ocaml/odoc): For the odoc tool, which generates styled HTML documentation from OCaml packages.
-- [ocaml-mdx](https://github.com/realworldocaml/mdx): For allowing us to execute code blocks within our markdown files, ensuring our documentation is always up to date.
+- [mdexp](https://github.com/mbarbin/mdexp): For authoring markdown files including compiled OCaml code fragment and generated contents, ensuring our documentation is always up to date.
 - [sherlodoc](https://github.com/art-w/sherlodoc): For its innovative approach to searching OCaml documentation.
 - [docusaurus](https://github.com/facebook/docusaurus): For providing a platform to bring all our documentation together in a user-friendly and accessible manner.
 

doc-experiment-docusaurus-dev.opam

@@ -10,12 +10,12 @@ bug-reports: "https://github.com/mbarbin/doc-experiment-docusaurus/issues"
 depends: [
   "dune" {>= "3.17"}
   "ocaml" {>= "5.2"}
+  "bisect_ppx" {>= "2.8.3"}
   "doc-experiment-docusaurus-tests" {= version}
   "mylib" {= version}
   "myotherlib" {= version}
-  "mdx" {>= "2.4"}
-  "ocamlformat" {= "0.28.1"}
-  "sherlodoc" {>= "0.2"}
+  "ocamlformat" {= "0.29.0"}
+  "sherlodoc" {>= "3.1.0"}
   "odoc" {with-doc}
 ]
 build: [

doc/docs/tutorials/hello-mylib/README.md

@@ -1,19 +1,29 @@
 # Hello Mylib
 
-Here we're making use of features offered by ocaml-mdx, with which we can keep
-the doc up to date.
+Here we're making use of [mdexp](https://github.com/mbarbin/mdexp) to keep
+the doc up to date. The code blocks below are extracted from an OCaml test
+file and their output is verified on every build.
 
 ## Using libraries
 
+We can make use of code defined in libraries in expect tests.
+
+```ocaml
+print_endline Mylib.hello_world;
+[%expect {| Hello, World! |}];
+```
+
+## Using Libraries in Toplevels
+
 We can make use of code defined in libraries.
 
 ```ocaml
-# print_endline Mylib.hello_world
+# print_endline Mylib.hello_world ;;
 Hello, World!
 - : unit = ()
 ```
 
-## Using executables
+## Using Executables in Cram Style
 
 We can make use of executables defined in packages.
 

doc/docs/tutorials/hello-mylib/dune

@@ -1,5 +1,31 @@
-(mdx
+(toplevel
+ (name mylib_toplevel)
+ (libraries mylib))
+
+(library
+ (name hello_mylib_doc)
+ (package doc-experiment-docusaurus-tests)
+ (libraries mylib unix)
+ (inline_tests
+  (deps mylib_toplevel.exe %{bin:mybin}))
+ (instrumentation
+  (backend bisect_ppx))
+ (preprocess
+  (pps ppx_expect)))
+
+(rule
+ (target README.output)
  (package doc-experiment-docusaurus-dev)
- (deps
-  (package mylib))
- (preludes prelude.txt))
+ (enabled_if %{bin-available:mdexp})
+ (deps readme.ml)
+ (action
+  (with-stdout-to
+   %{target}
+   (run %{bin:mdexp} pp %{deps}))))
+
+(rule
+ (package doc-experiment-docusaurus-dev)
+ (enabled_if %{bin-available:mdexp})
+ (alias runtest)
+ (action
+  (diff README.md README.output)))

doc/docs/tutorials/hello-mylib/readme.ml

@@ -0,0 +1,86 @@
+(* @mdexp
+
+   # Hello Mylib
+
+   Here we're making use of [mdexp](https://github.com/mbarbin/mdexp) to keep
+   the doc up to date. The code blocks below are extracted from an OCaml test
+   file and their output is verified on every build. *)
+
+let eval_toplevel code =
+  let code = String.trim code in
+  Printf.printf "# %s\n" code;
+  let cmd = "./mylib_toplevel.exe -noprompt -no-version" in
+  let ic, oc, ec = Unix.open_process_full cmd [||] in
+  output_string oc code;
+  output_char oc '\n';
+  close_out oc;
+  let stdout_content = In_channel.input_all ic in
+  let stderr_content = In_channel.input_all ec in
+  let status = Unix.close_process_full (ic, oc, ec) in
+  let stdout_trimmed = String.trim stdout_content in
+  if String.length stdout_trimmed > 0 then print_endline stdout_trimmed;
+  let stderr_trimmed = String.trim stderr_content in
+  if String.length stderr_trimmed > 0 then print_endline stderr_trimmed [@coverage off];
+  match status with
+  | WEXITED 0 -> ()
+  | _ ->
+    (match[@coverage off] status with
+     | WEXITED n -> Printf.printf "[%d]\n" n
+     | WSIGNALED n -> Printf.printf "[signal %d]\n" n
+     | WSTOPPED n -> Printf.printf "[stopped %d]\n" n)
+;;
+
+let mybin args =
+  let cmd = String.concat " " ("mybin" :: args) in
+  Printf.printf "$ %s\n" cmd;
+  let ic = Unix.open_process_in cmd in
+  print_string (In_channel.input_all ic);
+  ignore (Unix.close_process_in ic)
+;;
+
+(* @mdexp
+
+   ## Using libraries
+
+   We can make use of code defined in libraries in expect tests. *)
+
+let%expect_test "using libraries" =
+  (* @mdexp.code *)
+  print_endline Mylib.hello_world;
+  [%expect {| Hello, World! |}];
+  (* @mdexp.end *)
+  ()
+;;
+
+(* @mdexp
+
+   ## Using Libraries in Toplevels
+
+   We can make use of code defined in libraries. *)
+
+let%expect_test "using libraries" =
+  eval_toplevel {| print_endline Mylib.hello_world ;; |};
+  (* @mdexp.snapshot { lang: "ocaml" } *)
+  [%expect
+    {|
+    # print_endline Mylib.hello_world ;;
+    Hello, World!
+    - : unit = ()
+    |}]
+;;
+
+(* @mdexp
+
+   ## Using Executables in Cram Style
+
+   We can make use of executables defined in packages. *)
+
+let%expect_test "using executables" =
+  mybin [ "print" ];
+  (* @mdexp.snapshot { lang: "bash" } *)
+  [%expect
+    {|
+    $ mybin print
+    Hello, World!
+    |}]
+;;

doc/src/pages/index.md

@@ -1,7 +1,7 @@
 <h1 align="center">
   <p align="center">OCaml Documentation with Docusaurus and Odoc</p>
   <img
-    src="./img/doc-experiment.png?raw=true"
+    src="/doc-experiment-docusaurus/img/doc-experiment.png"
     width='384'
     alt="Logo"
   />

dune-project

@@ -15,8 +15,6 @@
 
 (documentation "https://mbarbin.github.io/doc-experiment-docusaurus/")
 
-(using mdx 0.4)
-
 (implicit_transitive_deps false)
 
 (package
@@ -37,11 +35,7 @@
  (synopsis "Another package named myotherlib in this project")
  (depends
   (ocaml
-   (>= 5.2))
-  (cmdlang
-   (>= 0.0.9))
-  (cmdlang-cmdliner-err-runner
-   (>= 0.0.16))))
+   (>= 5.2))))
 
 (package
  (name doc-experiment-docusaurus-tests)
@@ -66,15 +60,15 @@
  (depends
   (ocaml
    (>= 5.2))
+  (bisect_ppx
+   (>= 2.8.3))
   (doc-experiment-docusaurus-tests
    (= :version))
   (mylib
    (= :version))
   (myotherlib
    (= :version))
-  (mdx
-   (>= 2.4))
   (ocamlformat
-   (= 0.28.1))
+   (= 0.29.0))
   (sherlodoc
-   (>= 0.2))))
+   (>= 3.1.0))))

dune-workspace-5.4

@@ -3,11 +3,15 @@
 (pkg enabled)
 
 (lock_dir
- (repositories overlay upstream mbarbin)
+ (repositories overlay upstream alpha mbarbin)
  (constraints
   (ocaml
    (= 5.4.1))))
 
 (repository
  (name mbarbin)
  (url "git+https://github.com/mbarbin/opam-repository.git"))
+
+(repository
+ (name alpha)
+ (url "git+https://github.com/kit-ty-kate/opam-alpha-repository.git"))

dunolint

@@ -1,10 +1,24 @@
 (lang dunolint 1.0)
 
+;; Everything is instrumented
+
+(rule
+ (enforce
+  (dune
+   (instrumentation
+    (backend bisect_ppx)))))
+
+;; Test lib naming
+
 (rule
  (cond
-  ((path (glob test/**))
+  ((path
+    (glob test/**))
    (enforce
     (dune
      (library
-      (and (not (has_field public_name))
-       (package (equals doc-experiment-docusaurus-tests)))))))))
+      (and
+       (not
+        (has_field public_name))
+       (package
+        (equals doc-experiment-docusaurus-tests)))))))))

myotherlib.opam

@@ -10,8 +10,6 @@ bug-reports: "https://github.com/mbarbin/doc-experiment-docusaurus/issues"
 depends: [
   "dune" {>= "3.17"}
   "ocaml" {>= "5.2"}
-  "cmdlang" {>= "0.0.9"}
-  "cmdlang-cmdliner-err-runner" {>= "0.0.16"}
   "odoc" {with-doc}
 ]
 build: [

src/mylib/bin/dune

@@ -3,4 +3,6 @@
  (public_name mybin)
  (package mylib)
  (flags :standard -w +a-4-40-41-42-44-45-48-66 -warn-error +a)
- (libraries cmdlang-cmdliner-err-runner dune-build-info mylib))
+ (libraries cmdlang-cmdliner-err-runner dune-build-info mylib)
+ (instrumentation
+  (backend bisect_ppx)))

src/mylib/dune

@@ -3,4 +3,6 @@
  (public_name mylib)
  (flags :standard -w +a-4-40-41-42-44-45-48-66 -warn-error +a -open Cmdlang)
  (libraries cmdlang)
+ (instrumentation
+  (backend bisect_ppx))
  (preprocess no_preprocessing))

src/myotherlib/dune

@@ -1,6 +1,8 @@
 (library
  (name myotherlib)
  (public_name myotherlib)
- (flags :standard -w +a-4-40-41-42-44-45-48-66 -warn-error +a -open Cmdlang)
- (libraries cmdlang)
+ (flags :standard -w +a-4-40-41-42-44-45-48-66 -warn-error +a)
+ (libraries)
+ (instrumentation
+  (backend bisect_ppx))
  (preprocess no_preprocessing))

src/myotherlib/myotherlib.ml

@@ -1,11 +1 @@
 let hello_world = "Hello, World From My Other Lib!"
-
-let print_cmd =
-  Command.make
-    ~summary:"print hello world"
-    (let open Command.Std in
-     let+ () = Arg.return () in
-     print_endline hello_world)
-;;
-
-let main = Command.group ~summary:"" [ "print", print_cmd ]

src/myotherlib/myotherlib.mli

@@ -1,2 +1 @@
 val hello_world : string
-val main : unit Command.t

test/mylib/dune

@@ -4,5 +4,7 @@
  (flags :standard -w +a-4-40-41-42-44-45-48-66 -warn-error +a)
  (libraries mylib)
  (inline_tests)
+ (instrumentation
+  (backend bisect_ppx))
  (preprocess
   (pps ppx_expect)))

test/myotherlib/dune

@@ -4,5 +4,7 @@
  (flags :standard -w +a-4-40-41-42-44-45-48-66 -warn-error +a)
  (libraries myotherlib)
  (inline_tests)
+ (instrumentation
+  (backend bisect_ppx))
  (preprocess
   (pps ppx_expect)))