About

Entangled helps you write Literate Programs in Markdown. You put all your code inside Markdown code blocks. Entangled automatically extracts the code and writes it to more traditional source files. You can then edit these generated files, and the changes are being fed back to the Markdown.

We’re trying to increase the visibility of Entangled. If you like Entangled, please consider adding this badge to the appropriate location in your project:

[![Entangled badge](https://img.shields.io/badge/entangled-Use%20the%20source!-%2300aeff)](https://entangled.github.io/)

Get Started

With the 2.0 release, Entangled is now available as a Python package, installable through pip,

pip install entangled_cli

Write Markdown

“A critical aspect of a programming language is the means it provides for using names to refer to computational objects.” Abelson, Sussman & Sussman - SICP

Name your code

 The square of the hypothenuse is the sum
 of the two right-angled sides squared:
 $$a^2 + b^2 = c^2$$

 ``` {.python #pythagoras}
 def vector_length(x, y):
     return sqrt(x**2 + y**2)
 ```

def vector_length(x, y):
    return sqrt(x**2 + y**2)

“Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.” Knuth - Literate Programming

Compose your program

 To count the words in a sentence, first
 split the sentence into words, then
 count the number of words in the list.

 ``` {.python #word-count}
 def word_count(sentence):
     <<split-into-words>>
     <<count-words>>
     return count
 ```

 The default arguments to the `.split`
 method split on any white space.

 ``` {.python #split-into-words}
 words = sentence.split()
 ```

 Counting is done with the `length`
 function.

 ``` {.python #count-words}
 count = len(words)
 ```

def word_count(sentence):
    <<split-into-words>>
    <<count-words>>
    return count

words = sentence.split()

count = len(words)

“Talk is cheap. Show me the code.” Linus Torvalds

Documentation

• Tutorial: setting up a Literate project
• User Manual
• Example gallery
• Use MkDocs to publish

Bootstrap web template for Pandoc

To help you easily create a presentable website from your literate code, we provide a Bootstrap template for Pandoc. Probably the best way to use this template, is to fork our repository at entangled/bootstrap-submodule, and add your fork as a submodule in your project:

    git submodule add git@github.com:<my bootstrap-submodule fork>

This way you can tweak the template to your own wishes. If you want to play around first, you can also use the cookiecutter template,

    cookiecutter https://github.com/entangled/bootstrap

but this approach is less flexible. For more information, see the tutorial.

External Links

Blogs

• Why all you’ll ever need is Markdown — Introduction to Pandoc, and Pandoc filters.
• Entangled, a bi-directional Literate Programming tool — Presenting Entangled, a tool for pain free literate programming.
• Literate Programming in Science: the why — Explaining why Literate Programming is particularly well matched with scientific programming.
• Literate Programming in Science: the how — Showing methods for Literate Programming, comparing Entangled to Jupyter, RMarkdown and Org-mode.
• Unweaving legacy code using Entangled — Showing how you can use Entangled to reverse-engineer unreadable legacy code.

Literate Books

These are some awesome books written with a literate philosophy in mind.

Pharr, Jakob & Humphreys - Physically Based Rendering

Explains physically realistic 3D rendering, while implementing the same techniques in C++. This book is so amazing, it actually won an Acadamy Award for technical achievement. The book uses the same noweb notation for code block references we do.

PBRT

Sussman & Wisdom - Structure and Interpretation of Classical Mechanics

Does not use noweb, but subscribes to the many founding principles of literate programming. This is a text book on classical mechanics and specifically the Lagrangian and Hamiltonian descriptions of physics.

SICM

Hudak & Quick - The Haskell School of Music

From signals to symphonies, this book fuses the authors’ passion for music and the Haskell programming language.

HSOM

Pandoc filters

• Knitty — Expands code-cells through a Jupyter interface. Uses Panflute.
• pandocsql — Inserts tables in your markdown into an Sqlite database, and run queries that appear as tables in the output. Uses Panflute.

Dev tools

• Panflute — A “Pythonic” interface for creating Pandoc filters.