Discussion

Markdown for literate programming

Alternative source files

    import pidgy, pandas, types, builtins, pathlib

import pidgy, pandas, types, builtins, pathlib

pidgy is a literate program and it 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.

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

pidgy is a literate program and it 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.

<tr style="text-align: right;">
  <th></th>
  <th>.md</th>
  <th>.ipynb</th>
  <th>.py</th>
</tr>

<tr>
  <th>extensions</th>
  <td>7</td>
  <td>3</td>
  <td>2</td>
</tr>

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

## Shebangs

Perhaps one of the more damning shortcomings of the notebook is that it is no a script, and requires specialized software to execute.

`pidgy` markdown documents can begin with a shebang line that defines how the
script should be executed.

```bash
#!/usr/bin/env python -m pidgy run file.md
```

When the shebang is included the markdown file can be executed at the command line with a preceeding period.

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

Shebangs

Perhaps one of the more damning shortcomings of the notebook is that it is no a script, and requires specialized software to execute.

pidgy markdown documents can begin with a shebang line that defines how the script should be executed.

#!/usr/bin/env python -m pidgy run file.md

When the shebang is included the markdown file can be executed at the command line with a preceeding period.

./file.md

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

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.

## Best practices for literate programming in Markdown

    import json
Our core moral commitment is to write literate programs, because:

> ...; surely nobody wants to admit writing an illiterate program.
>
> > - [Donald Knuth] _[Literate Programming]_

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

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

* [Markdown] documents are sufficient for literate progr.

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

* First markdown cell is the docstring

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

Best practices for literate programming in Markdown

import json

Our core moral commitment is to write literate programs, because:

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

• Donald Knuth `Literate Programming <#>`__

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

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

• Markdown documents are sufficient for literate progr.

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 in doubt, abide Web Content Accessibility Guidelines so that information can be accessed by differently abled audiences.
• First markdown cell is the docstring

## External tools

`pidgy` works jupyter notebook, jupyterlab, nteract, and colab.

External tools

pidgy works jupyter notebook, jupyterlab, nteract, and colab.

# Conclusion

Markdown documents represent a compact form of a literate programming.

Conclusion

Markdown documents represent a compact form of a literate programming.