unikernel/duniverse/dune_/doc/reference/dune/mdx.rst

@@ -0,0 +1,75 @@
+mdx
+---
+
+.. versionadded:: 2.4
+
+MDX is a tool that helps you keep your markdown documentation up-to-date by
+checking that its code examples are correct. When setting an MDX stanza, the MDX
+checks are automatically attached to the ``runtest`` alias of the stanza's
+directory.
+
+See `MDX's repository <https://github.com/realworldocaml/mdx>`__ for more
+details.
+
+You can define an MDX stanza to specify which files you want checked.
+
+Note that this feature is still experimental and needs to be enabled in your
+``dune-project`` with the following ``using`` stanza:
+
+.. code:: dune
+
+  (using mdx 0.4)
+
+.. note:: Version ``0.2`` of the stanza requires mdx ``1.9.0``. Version ``0.4``
+   of the stanza requires mdx ``2.3.0``.
+
+
+The syntax is as follows:
+
+.. code:: dune
+
+  (mdx <optional-fields>)
+
+Where ``<optional-fields>`` are:
+
+- ``(files <globs>)`` are the files that you want MDX to check, described as a
+  list of globs (see the :ref:`Glob language specification <glob>` ). It
+  defaults to ``*.md *.mld`` as of version ``0.4`` of the stanza and ``*.md``
+  before.
+
+- ``(deps <deps-conf list>)`` to specify the dependencies of your documentation
+  code blocks. See :doc:`/concepts/dependency-spec` for more details.
+
+- ``(preludes <files>)`` are the prelude files you want to pass to MDX. See
+  `MDX's documentation <https://github.com/realworldocaml/mdx>`__ for more
+  details on preludes.
+
+- ``(libraries <libraries>)`` are libraries that should be statically linked in
+  the MDX test executable.
+
+- ``(enabled_if <blang expression>)``  is the same as the corresponding field of
+  :doc:`library`.
+
+- ``(package <package>)`` specifies which package to attach this stanza to
+  (similarly to when ``(package)`` is attached to a ``(rule)`` stanza). When
+  ``-p`` is passed, ``(mdx)`` stanzas with another package will be ignored. Note
+  that this feature is completely separate from ``(packages)``, which specifies
+  some dependencies.
+
+- ``(locks <lock-names>)`` specifies that the action of running the tests
+  holds the specified locks. See :doc:`/concepts/locks` for more details.
+
+Upgrading from Version 0.1
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- The 0.2 version of the stanza requires at least MDX 1.9.0. If you encounter an
+  error such as, ``ocaml-mdx: unknown command `dune-gen'``, then you should
+  upgrade MDX.
+
+- The field ``(packages <packages>)`` is deprecated in version 0.2. You can use
+  package items in the generic ``deps`` field instead: ``(deps (package
+  <package>) ... (package <package>))``
+
+- Use the new ``libraries`` field to directly link libraries in the test
+  executable and remove the need for ``#require`` directives in your
+  documentation code blocks.