Repository files navigation

midgy transforms markdown to python modules and scripts.

midgy README.md# run a readme file as pythonmidgy run README.md# run a readme file as pythonmidgy -m README# run a readme file as python

  >>> from midgy.run import Markdown  >>> with Markdown():  ...   import README  >>> print(README)  <module 'README' from '...README.md'>

midgy is one half ofpidgy, together they bring literate programming and computing afforandances to [python] and [IPython].midgy is only concerned with the half of literate programming that translates a document to compiled code.midgy has a small api:

• md_to_python - a function that converts a markdown document to python
• Python - a class that parses a markdown document and renders python
• midgy.run.Markdown - is animportnb context manager that includes markdown documents when importing python modules.

literate programming is paradigm that treats code as literate, and vice versa; documents are evaluated on their literary and computational qualities. there are two actions defined in the framework of literate programming:

1. render: the act of translating the document into a programming language:midgy renders markdown to python
2. weave: the act of translating the document to a rendered format:pidgy weaves markdown to html, pdf, or md through thejinja2 template system.

midgy focuses only on therender actions, and is extended inpidgy which implements the weave action.

midgy extends the commonmark spec to reflect some common conventions.

1. shebang:midgy documents are programs and may begin with a shebang.
2. front matter: can be included at the beginning of a document or after a shebang.: either toml, json or yaml can be used
3. doctest: a literate programming convention for including tests in python strings
4. code: our code blocks are modified to be aware of doctests and include lexical diagnostics of the content

midgy translates markdown to python relative to indented code blocks. content between indented code blocks are wrapped a python block strings, and non-indented code blocks can be included in python programs. the translation from markdown to python is meant to require the fewest changes to have valid python code.

midgy goes to great lengths to generate a line-for-line translation of the markdown to python.the line-for-line translation improves the error handling experience when using non-python documents as modules.

  from sys import argv  print(argv)