mdx¶
New in version 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 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:
(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:
(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 Glob language specification ). It defaults to*.md *.mld
as of version0.4
of the stanza and*.md
before.(deps <deps-conf list>)
to specify the dependencies of your documentation code blocks. See Dependency Specification for more details.(preludes <files>)
are the prelude files you want to pass to MDX. See MDX’s documentation 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 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 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 genericdeps
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.