Skip to content

Instantly share code, notes, and snippets.

@tonyfast

tonyfast/__init__.py

Last active February 25, 2020 04:14
Show Gist options
  • Save tonyfast/2947b4bb582e193f5b2a7dbf8b009b62 to your computer and use it in GitHub Desktop.
Save tonyfast/2947b4bb582e193f5b2a7dbf8b009b62 to your computer and use it in GitHub Desktop.
Download ZIP
The pidgy programming about a literate programming that speaks markdown and python. https://mybinder.org/v2/gist/tonyfast/2947b4bb582e193f5b2a7dbf8b009b62/master?filepath=index.ipynb
Raw
__init__.py
import pidgy
with pidgy.pidgyLoader():
try:
from . import intro
except:
import intro
with pidgy.pidgyLoader(main=__name__ == "__main__"):
try:
from . import readme
except:
import readme
Raw
readme.md

pidgy programming

Abstract

[Literate Programming] is a literary style that treats documents as having dual qualities of literature and computer programs. The original 1979 implementation defined the [WEB] metalanguage of [Latex] and [Pascal]. pidgy is modern and interactive take on [Literate Programming] that uses Markdown and Python as the respective document and programming languages, of course we'll add some other bits and bobs.

The result of the pidgy implementation is an interactive programming experience where authors design and program simultaneously in Markdown. An effective literate programming will use machine logic to supplement human logic to explain a program program. If the document is a valid module (ie. it can restart and run all), the literate programs can be imported as Python modules then used as terminal applications, web applications, formal testing object, or APIs. All the while, the program itself is a readable work of literature as html, pdf.

pidgy is written as a literate program using Markdown and Python. Throughout this document we'll discuss the applications and methods behind the pidgy and what it takes to implement a [Literate Programming] interface in IPython.

Topics

  • Literate Programming
  • Computational Notebooks
  • Markdown
  • Python
  • Jupyter
  • IPython

Author

Tony Fast

Raw
best-practices.md

Best practices for literate programming

The first obligation of the literate programmer, defined by Donald Knuth(ie. the prophet of Literate Programming), is a core moral commitment to write literate programs, because:

...; surely nobody wants to admit writing an illiterate program.

The following best practices for literate programming have emerged while desiging pidgy.

List of best practices

  • Restart and run all or it didn't happen.

    A document should be literate in all readable, reproducible, and reusable contexts.

  • When in doubt, abide Web Content Accessibility Guidelines so that information can be accessed by differently abled audiences.

  • Markdown documents are sufficient for single units of thought.

    Markdown documents that translate to python can encode literate programs in a form that is better if version control systems that the json format that encodes notebooks.

  • All code should compute.

    Testing code in a narrative provides supplemental meaning to the "code" signifiers. They provide a test of veracity at least for the computational literacy.

  • readme.md is a good default name for a program.

    Eventually authors will compose ["readme.md"] documents that act as both the "__init__" method and "__main__" methods of the program.

  • Each document should stand alone, despite all possibilities to fall.

  • Use code, data, and visualization to fill the voids of natural language.

  • Find pleasure in writing.

  • When writing narrative include one unit of meaning per line.

    A sentence represents the maximum unit that can be broken up into smaller diffable units. This approach will create cleaner histories in revision control systems.

Display the source blob
Display the rendered blob
Raw
figures.md.ipynb
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Display the source blob
Display the rendered blob
Raw
index.ipynb
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Raw
intro.md
tangle_weave_diagram

I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature.

Donald Knuth

Introduction

"Literate programming" is a paper published by Donald Knuth in 1979. It describes a multiobjective, multilingual style of programming that treats programs primarily as documentation. Literate programs have measures along two dimensions:

  1. the literary qualities determined the document formatting language.
  2. the computational qualities determined by the programming language.

The multilingual nature of literate program creates the opportunity for programmers and non-programmers to contribute to the same literature.

Literate programs accept "code" as an integral part of the narrative. "code" signs can be used in places where language lacks just as figures and equations are used in scientific literature. An advantage of "code" is that it can provide augmented representations of documents and their symbols that are tactile and interactive.

Tangle Weave Diagram

The literate program concurrently describes a program and literature. Within the document, natural language and the programming language interact through two different process:

  1. the tangle process that converts to the programming language.
  2. the weave process that converts to the document formatting language.

The original WEB literate programming implementation chose to tangle to Pascal and weave to Tex. pidgy's modern take on literate programming tangles to [Python] and weaves to [Markdown], and they can be written in either [Markdown] files or jupyter notebooks.

[Pascal] was originally chosen for its widespread use throughout education, and the same can be said for the choice of jupyter notebooks used for education in many programming languages, but most commonly [Python]. The preferred document language for the notebook is [Markdown] considering it is part of the notebook schema. CP4E The motivations made the natural choice for a [Markdown] and [Python] programming lanuage. Some advantages of this hybrid are that Python is idiomatic and sometimes the narrative may be explicitly executable.

Literate Programming is alive in places like Org mode for Emacs, RMarkdown, [Pweave], Doctest, or Literate Coffeescript. A conventional look at literate programming will place a focus on the final document. pidgy meanwhile places a focus on the interactive literate computing steps required achieve a quality document.

Originally, pidgy was designed specifically for the notebook file format, but it failed a constraint of not being an existing file. Now pidgy is native for [Markdown] files, and valid testing units. It turns out the [Markdown] documents can provide a most compact representation of literate program, relative to a notebook. And it diffs better.

Design constraints:

  • Use an existing file formats.
  • Minimal bespoke syntax.
  • Importable and testable

A last take on this work is to affirm the reproducibly of enthusiasm when writing literate programs.

The outcome of writing pidgy programs are readable, reusable, and reproducible documents.
pidgy natively supports importing markdown and notebooks as source code.

Modern computing has different pieces of software infrastructure than were available

Raw
postBuild
pidgy kernel install
Raw
requirements.txt
git+https://github.com/deathbeds/pidgy@edits
pandas
matplotlib
sklearn
@tonyfast
Copy link
Author

image

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment