Discussion¶

    import pidgy, jupyter

import pidgy, jupyter

## Markdown for literate programming

`pidgy` uses the Markdown formatting language because it is the native document format
for `jupyter`. Another motivation is the broad application of Markdown for literate 
progamming in different programming languages. Markdown could potentially provide a
generalized document for polyglot literate computing.

We find are two brands of Markdown programming implementations:

1. Those that use indented code blocks.
2. Those that use code fences.

`pidgy` follows the influence of literate coffeescript and focuses on the ability to tangle
code primarily written using indented code fences. It does accomodate code fences, but 
currently `pidgy` holds no opinion about how to treat code fence syntax like in RMarkdown and PWeave.

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

Non-consecutive header level increase; 0 to 2

## Alternative source files

    import wtypes, pandas, pathlib, types, builtins

When code is written primarily in source files, the literary quality of the program is 
always secondary to the computational qualities. `pidgy` includes the ability to use
alternative file schema to import literate documents as python modules, tests, and software.
The reusuability of `pidgy` programs means that each document can have multiple objectives of literary and computational quality.

`pidgy` is an implementation that follows many other experiements in interactive computing with notebooks.
`importnb` is a primary library of `pidgy` that customizes Python's import hooks.
When software begins from literate documents like notebooks and markdown files it can then mature
to scripts as each idea materializes. `importnb` and `wtypes` represent two projects that 
mature from notebook source files that are idea for fluid ideas to python scripts with
literate programs for tests and documentation.

`pidgy` uses a mix of files for its source.  Until, the tangle step
of literate programming we have to rely on available files with avaiable improters,
afterwards markdown is used as source.
Each file type has different capacities for encoding literate narratives.

* Python scripts favor language, but doctests represent literate source code for testing.
* Markdown scripts capture the full input for a literate program.
* Notebooks are hypermedia collages of literate programs that connect literate computing input to output.

{{file_counts.to_html()}}

    file_counts = pandas.Series({k:pathlib.Path(v.__file__).suffix for k,v in vars(pidgy).items() if isinstance(v, types.ModuleType) and v is not builtins}).value_counts().to_frame('extensions').T

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

Non-consecutive header level increase; 0 to 2

## Shebangs

    import json

Perhaps one of the more damning shortcomings of the notebook is that it is not a script, 
and requires specialized software to execute. Notebooks are encoded in `json` and cannot
include command lines. As a result, they cannot include a shebang line. One the other hand,
`pidgy` markdown files can include a shebang line that describes how a literate program
should tangle. `pidgy` has 3 options, run template test, should be tangle weave


An example `"file.md"` could begin with one of the following shebang statements

```bash
#!/usr/bin/env python -m pidgy run 
#!/usr/bin/env python -m pidgy template
#!/usr/bin/env python -m pidgy test
```

Then the markdown file can be executed at the command line with a preceeding period.

```bash
./file.md
```

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

Non-consecutive header level increase; 0 to 2

## Revision Control

Another struggle with notebooks is revision control, git is not the solution. Notebooks are data
and require a different strategy than git. Markdown documents on the other hand
capture the input of literate programming and diff really well.

## Outcomes

There are numerous outcomes of a source written literate code.  With `pidgy`
as an example we can do more than simply tangle and weave a program.

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

Non-consecutive header level increase; 0 to 2

## Best practices for literate programming in Markdown


* Programs should be literate.
* Restart and run all or it didn't happen.

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


* Start with natural language and a docstring.

  Most notebooks begin importing code, literate programs should begin importing
  natural language to describe a goal.

* 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.
* Each document should stand alone,
  [despite all possibilities to fall.](http://ing.univaq.it/continenza/Corso%20di%20Disegno%20dell'Architettura%202/TESTI%20D'AUTORE/Paul-klee-Pedagogical-Sketchbook.pdf#page=6)
* Use code, data, and visualization to fill the voids of natural language.
* Find pleasure in writing.
* When in doubt, abide [Web Content Accessibility Guidelines][wcag] so that
  information can be accessed by differently abled audiences.

                                       
[wcag]: https://www.w3.org/WAI/standards-guidelines/wcag/
[donald knuth]: #
[literate programming]: #
[markdown]: #
[readme.md]: #

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

Non-consecutive header level increase; 0 to 2

## External tools

Since `pidgy` relies on `jupyter`s open standards it works with jupyter notebook, 
jupyterlab, nteract, and colab. We were unable to spend creating plugins for Atom or VSCode.

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

Non-consecutive header level increase; 0 to 2

# Conclusion


Notebooks and Markdown files are substrates for literature backed by programming languages.
Choosing to write programs as literature can drastically improve the quality of program
that would otherwise rely on the programming language syntax. Authoring `pidgy` documents is
a fun experience that allows the author vascillate between writing code and narrative. The ability
to transclude interactive computation into documents gives authors the ability to access
new language and meaning when supplemented with code.

Pidgy Programming

Discussion¶