# MyST markdown

Manuel was originally written for reStructuredText. Starting with the `manuel.codeblock` module, Manuel will successively be extended for MyST, a Markdown flavor. Read about `MyST`.

## Code Blocks

Sphinx and other docutils extensions provide a `code-block` directive, which allows inlined snippets of code in MyST documents.

Several plug-ins are included that provide new test syntax (see Included Functionality). You can also create your own plug-ins.

For example, if you’ve ever wanted to include a large chunk of Python in a doctest but were irritated by all the `>>>` and `...` prompts required, you’d like the `manuel.myst.codeblock` module. It lets you execute code using MyST-style code block directives containing unpolluted Python code. The markup looks like this:

    ```python
    import foo

    def my_func(bar):
        return foo.baz(bar)
    ```

To get Manuel wired up, see Getting Started. To run doctests in MyST, use `manuel.myst.codeblock`.

The scope of variables spans across the complete document.

    a = 3

    # another variable
    b = 2 * 3

The variables `a` and `b` can be used in the subsequent code block.

    assert b == 6

For better test feedback, you can use the methods of `unittest.TestCase`.

    self.assertEqual(b, 6)

The output of `self.assertEqual(b, 9999)` would be the following.

    AssertionError: 6 != 9999

You can even write code in invisible code blocks. Invisible code blocks do not show up in the rendered documentation. Using MyST syntax, lines that start with `%` are comments. The markup looks like this:

    % invisible-code-block: python
    %
    % self.assertEqual(a+b, 9)
    %
    % self.assertEqual(7 * a, 21)

Invisible code blocks are tested like normal code blocks.

Happy hacking!