Add MDX in with-test deps

Author: xvw

CREDITS.md

@@ -1,47 +1,59 @@
 # Preface
 
 Preface is a free (an open-source) library written in (and for)
-[OCaml](https://ocaml.org) and released under the [MIT license](LICENSE)
-The library is mainly maintained by:
+[OCaml](https://ocaml.org) and released under the [MIT
+license](LICENSE) The library is mainly maintained by:
 
 - [Didier Plaindoux](https://github.com/d-plaindoux)
 - [Pierre Ruyter](https://github.com/gr-im)
 - [Xavier Van de Woestyne](https://github.com/xvw/)
 
 ### Warm thanks and help
 
-- [Gabriel Scherer](https://github.com/gasche) for many design choice and
-  technical help about specific subject
-- [Andrey Mokhov](https://github.com/snowleopard) for his help in understanding
-  Selectives (and Free Selective) and constant reviews related to Selectives
-- [Florian Angeletti](https://github.com/Octachron) for advices and help
+- [Gabriel Scherer](https://github.com/gasche) for many design choice
+  and technical help about specific subject
+- [Andrey Mokhov](https://github.com/snowleopard) for his help in
+  understanding Selectives (and Free Selective) and constant reviews
+  related to Selectives
+- [Florian Angeletti](https://github.com/Octachron) for advices and
+  help
 - [Oleg Kiselyov](http://okmij.org/ftp) for advices about Freer monad
-- [XHTMLBoy](https://github.com/xhtmlboi) for providing an implementation of Freer capable of not executing the continuation
-- [Pierre-Evariste Dagand](https://pages.lip6.fr/Pierre-Evariste.Dagand/) for a lot of help with Arrows
+- [XHTMLBoy](https://github.com/xhtmlboi) for providing an
+  implementation of Freer capable of discarding the continuation
+- [Pierre-Evariste
+  Dagand](https://pages.lip6.fr/Pierre-Evariste.Dagand/) for a lot of
+  help with Arrows
 
 ## Used libraries
 
-Preface use several libraries (especially for unit tests). For more information,
-feel free to refer to the OPAM files located at the root of the project.
-Here is a list of our dependancies:
+Preface use several libraries (especially for unit tests). For more
+information, feel free to refer to the OPAM files located at the root
+of the project.  Here is a list of our dependancies:
 
 - [Alcotest](https://github.com/mirage/alcotest) - for the definition
   of unit tests
-- [QCheck](https://github.com/c-cube/qcheck) - for the definition of properties
-  based testing (coupled with Alcotest)
+- [QCheck](https://github.com/c-cube/qcheck) - for the definition of
+  properties based testing (coupled with Alcotest)
+- [Either](https://github.com/mirage/either) - for having an
+  `Either.t` before OCaml `4.12`
+- [mdx](https://github.com/realworldocaml/mdx) - for guide as tests
 
 
 ## Used tools
 
-In addition to [OCaml](https://ocaml.org), we use tools from the OCaml ecosystem:
+In addition to [OCaml](https://ocaml.org), we use tools from the OCaml
+ecosystem:
 
-- [Dune](https://github.com/ocaml/dune) - as a build system (and task runner)
-- [OCamlformat](https://github.com/ocaml-ppx/ocamlformat) - as a code formatter
-  in order to keep our code formatted according to fixed standards.
-- [Odoc](https://github.com/ocaml/odoc) - as a documentation generator.
+- [Dune](https://github.com/ocaml/dune) - as a build system (and task
+  runner)
+- [OCamlformat](https://github.com/ocaml-ppx/ocamlformat) - as a code
+  formatter in order to keep our code formatted according to fixed
+  standards.
+- [Odoc](https://github.com/ocaml/odoc) - as a documentation
+  generator.
 
 In addition, we use [Merlin](https://github.com/ocaml/merlin) and
-[Tuareg](https://github.com/ocaml/tuareg) or
-[OCaml mode](https://github.com/ocaml/caml-mode) as IDE. For the more
+[Tuareg](https://github.com/ocaml/tuareg) or [OCaml
+mode](https://github.com/ocaml/caml-mode) as IDE. For the more
 adventurous with more RAM
 [IntelliJ](https://plugins.jetbrains.com/plugin/4986-ocaml-support).

dune-project

@@ -1,2 +1,4 @@
 (lang dune 2.8)
 (name preface)
+(using mdx 0.1)
+(package (name preface))

guides/dune

@@ -0,0 +1,3 @@
+(mdx
+  (packages preface)
+  (files *.md))

guides/test.md

@@ -0,0 +1,104 @@
+```ocaml
+# #require "preface"
+```
+
+# A deep dive into the modular breakdown of Preface
+
+Preface uses a modular cut that can be complex at first glance. In
+this guide, we will see how to implement several abstractions, in
+several ways, for the `option` type. Preface's design choice are
+briefly explained/described [on the
+README](https://github.com/xvw/preface#some-design-choices)
+
+## Giving a Functor to our Option
+
+Although cutting is daunting, Preface tries as much as possible to
+offer an "easy" approach, which we will call the "*Happy Path*". For
+example, let's add a `Functor` for `option`.  The most standard
+approach to building a Functor is to provide a parameterised type and
+a map function. So, we could use the module
+`Preface.Make.Functor.Via_map` and give it a module of type:
+`Preface.Specs.Functor.WITH_MAP` respecting this interface:
+
+```ocaml
+# #show Preface.Specs.Functor.WITH_MAP
+module type WITH_MAP = sig type 'a t val map : ('a -> 'b) -> 'a t -> 'b t end
+```
+
+Now that we know how to implement a `Functor`, let's do it.
+
+```ocaml
+module Opt_functor = Preface.Make.Functor.Via_map (struct
+  type 'a t = 'a option 
+  let map f = function 
+    | Some x -> Some (f x) 
+    | None -> None
+end) 
+```
+
+Let's see if the whole interface has been implemented:
+
+```ocaml
+# #show Opt_functor
+module Opt_functor :
+  sig
+    type 'a t = 'a option
+    val map : ('a -> 'b) -> 'a option -> 'b option
+    val replace : 'a -> 'b option -> 'a option
+    val void : 'a option -> unit option
+    module Infix : sig ... end
+    val ( <$> ) : ('a -> 'b) -> 'a option -> 'b option
+    val ( <&> ) : 'a option -> ('a -> 'b) -> 'b option
+    val ( <$ ) : 'a -> 'b option -> 'a option
+    val ( $> ) : 'a option -> 'b -> 'b option
+  end
+```
+
+Perfect. Now let's try to use our freshly created combinators.
+
+```ocaml
+# Opt_functor.(succ <$> Some 10)
+- : int option = Some 11
+```
+
+For many objects, it is generally not necessary to go further than the
+minimum definition. It allows to derive a complete interface by
+implementing relatively few functions (just the bare necessities).
+
+## Giving a monad to our option
+
+`Functor` is a special case because it offers only one definition
+path. On the other hand, `Monad` is a bit more interesting, as it is
+possible to describe a monad in three different ways:
+
+1. Using `return` and `bind`
+2. Using `return`, `map` and `join`
+3. Using `return`, and the kleisli composition.
+
+For this tutorial, we will see how to build a `Monad` module using the
+first two strategies.
+
+### Using Bind
+
+This is generally the most standard way to describe a monad (at least
+in the Haskell world). First Let's see what requirements are needed to
+build a monad with `bind` (and `return`):
+
+```ocaml
+# #show Preface.Specs.Monad.WITH_BIND
+module type WITH_BIND =
+  sig
+    type 'a t
+    val return : 'a -> 'a t
+    val bind : ('a -> 'b t) -> 'a t -> 'b t
+  end
+```
+
+> You may have noticed that the signature is called `WITH_BIND` and
+> not `WITH_RETURN_AND_BIND`. This is an internal Preface
+> convention. When a function must be provided in all minimal
+> definitions, it is mandatory and therefore not repeated in its
+> module name.
+
+
+

lib/preface_core/dune

@@ -1,4 +1,4 @@
 (library
  (name preface_core)
- (package preface)
+ (public_name preface.core)
  (libraries either))

lib/preface_make/dune

@@ -2,4 +2,4 @@
  (name preface_make)
  (public_name preface.make)
  (modules_without_implementation preface_make)
- (libraries either preface_core preface.specs))
+ (libraries either preface.core preface.specs))

preface.opam

@@ -28,6 +28,7 @@ depends: [
   "alcotest" {with-test}
   "qcheck-core" {with-test}
   "qcheck-alcotest" {with-test}
+  "mdx" {with-test}
   "odoc"{with-doc}
 ]