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.

```alangage
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.

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.

Add alanguage specification to code fence to ignore its input.

Or, use html tags.

I am explicit HMTL.

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.

Emergent language features

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

### 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.

    class MyClass:

The same goes for class definitions.

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

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

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.

class MyClass:

The same goes for class definitions.

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

# NBVAL_SKIP

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
...