76 lines
2.6 KiB
ReStructuredText
76 lines
2.6 KiB
ReStructuredText
|
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.
|