`pidgy` metasyntax¶

    import pidgy, IPython, jinja2, doctest

`pidgy` not only allows the [Markdown] and [Python] to cooperate in a document, 
metasyntaxes emerge at the interface between the language.

import pidgy, IPython, jinja2, doctest

pidgy not only allows the [Markdown] and [Python] to cooperate in a document, metasyntaxes emerge at the interface between the language.

Markdown is the primary language¶

`pidgy` considers [Markdown] indented code blocks and language free code fences
as valid [Python] code while every other object is represented as a triple 
quoted block string.

    print("Indented blocks are always code like in literate coffeescript.")

Indented blocks are always code like in literate coffeescript.

pidgy considers [Markdown] indented code blocks and language free code fences as valid [Python] code while every other object is represented as a triple quoted block string.

print("Indented blocks are always code like in literate coffeescript.")

Executing code.¶

There are two specific to ensure that code is executed in `pidgy`.

### Indented code.

Like in the prior cell, an indented code block is a specific token in Markdown
that `pidgy` recognizes canonically as code.

    "This is code" # because of the indent.

### Code fences.

```
"I am code because no language is specified."
```

### Ignoring code.

Include a language with the code fence to skip code execution.

```alanguage
Add alanguage specification to code fence to ignore its input.
```

Or, use html tags.

<pre><code>
I am explicit HMTL.
</code></pre>

There are two specific to ensure that code is executed in pidgy.

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/pidgy/checkouts/docs/pidgy/tests/test_pidgin_syntax.md.ipynb, line 3)

Non-consecutive header level increase; 0 to 3

Testing code¶

`pidgy` recognizes doctests, a literate programming approach to testing, in the input and executes them in a formal unittest
testing suite. `doctest` are identified by the `">>>"` line prefix.

    >>> assert True
    >>> print
    <built-in function print>
    >>> pidgy
    <module...__init__.py'>

pidgy recognizes doctests, a literate programming approach to testing, in the input and executes them in a formal unittest testing suite. doctest are identified by the ">>>" line prefix.

>>> assert True
>>> print
<built-in function print>
>>> pidgy
<module...__init__.py'>

Weaving and templating code¶

`pidgy` permits the popular `jinja2` templating syntax.  Any use of 
templates references <code>{% raw %}{{}}{% endraw %}</code> will be filled in with
information from the current namespace.

There is a variable `foo` with the value <code>{{foo}}</code>.

    foo = 20

pidgy permits the popular jinja2 templating syntax. Any use of templates references {{}} will be filled in with information from the current namespace.

There is a variable foo with the value 20.

foo = 20

Suppressing the weave output.¶



`pidgy` will not render any input beginning with a blank line.

# Front matter

---
a: foo
---

`import ruamel.yaml` front matter starts with `"---"`.

    assert a == 'foo'

import ruamel.yaml front matter starts with "---".

assert a == 'foo'

+++
[a]
b="foo"
+++

`import toml` front matter starts with `"+++"`.

    assert a == {'b': 'foo'}

import toml front matter starts with "+++".

assert a == {'b': 'foo'}

Emergent language features¶

Interleaving Markdown and Python results in natural metasyntaxes that allow
`pidgy` authors to write programs that look like documentation.

    markdown_block =\
    
This is a markdown block.

### Docstrings.

[Markdown] that follows function and class definitions are wrapped as block strings
and indented according `pidgy`'s heuristics. What results is the [Markdown]
represents the docstring.

    def my_function():

`my_function` demonstrates how docstrings are defined.

        >>> assert any(x.lstrip().startswith('>>>') for x in my_function.__doc__.splitlines()), "The doctest isn't in the docstring"

Interleaving Markdown and Python results in natural metasyntaxes that allow pidgy authors to write programs that look like documentation.

markdown_block =\

This is a markdown block.

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/pidgy/checkouts/docs/pidgy/tests/test_pidgin_syntax.md.ipynb, line 8)

Non-consecutive header level increase; 0 to 3

    class MyClass:

The same goes for class definitions.

    ...
    >>> my_function.__doc__
    '`my_function` demonstrates how ...'
    >>> MyClass.__doc__
    'The same goes for class definitions.'

class MyClass:

The same goes for class definitions.

...
>>> my_function.__doc__
'`my_function` demonstrates how ...'
>>> MyClass.__doc__
'The same goes for class definitions.'

Interactive Testing¶

Failures are treated as natural outputs of the documents. Tests may fail, but parts of the unit may be reusable.

def test_functions_start_with_test():
    assert False, "False is not True"
    assert False is not True
...

Pidgy Programming

pidgy metasyntax¶